@homeflare/distilled-unifi-network 0.2.0

package/src/errors.ts

@@ -0,0 +1,103 @@
+/**
+ * UniFi Network-specific error types.
+ *
+ * ⛔ THE SPEC DOCUMENTS ZERO ERROR RESPONSES. Every one of the 73 operations
+ * in `network_v10.4.57_openapi.json` declares only its success status (65
+ * carry `200`, 8 carry `201`) — there is no per-operation 4xx/5xx, and
+ * unlike Hetzner's spec there isn't even a blanket `4xx`/`5xx` wildcard to
+ * signal "any of these can happen." So there is nothing for the OpenAPI→
+ * Smithy converter to type per operation (see `scripts/convert.ts`'s
+ * `statusToErrorClass: {}`), and every generated operation's error channel
+ * is the SAME open set below, dispatched purely by HTTP status at runtime
+ * (`src/protocol.ts`, `@distilled.cloud/core/errors#HTTP_STATUS_MAP`) —
+ * exactly the situation core's shared map exists for, just with less
+ * upstream signal than usual to say which statuses are actually reachable.
+ *
+ * Re-exports the common HTTP errors from core (nothing UniFi-specific to
+ * add to the status→class mapping — no documented error envelope shape,
+ * either, so `UnknownUnifiNetworkError` below carries the raw body rather
+ * than any parsed `code`/`message` pair) plus the unknown-error and
+ * parse-error wrappers every package needs.
+ *
+ * Known unknowns — confirm against a live console before hardening on them:
+ *   - Exact body shape of a failure (no operation's `responses` gives one).
+ *   - Whether 429 carries `Retry-After` (assume not; see `src/retry.ts`).
+ *   - Whether a bad/missing `X-API-KEY` answers 401 or 403 (both are wired
+ *     through `HTTP_STATUS_MAP`; only one will actually fire).
+ */
+export {
+  BadGateway,
+  BadRequest,
+  Conflict,
+  ConfigError,
+  Forbidden,
+  GatewayTimeout,
+  InternalServerError,
+  NotFound,
+  ServiceUnavailable,
+  TooManyRequests,
+  Unauthorized,
+  UnprocessableEntity,
+  HTTP_STATUS_MAP,
+  DEFAULT_ERRORS,
+  API_ERRORS,
+} from "@distilled.cloud/core/errors";
+import type {
+  BadRequest as CoreBadRequest,
+  Conflict as CoreConflict,
+  DefaultErrors as CoreDefaultErrors,
+  Forbidden as CoreForbidden,
+  NotFound as CoreNotFound,
+  UnprocessableEntity as CoreUnprocessableEntity,
+} from "@distilled.cloud/core/errors";
+
+import * as Schema from "effect/Schema";
+import * as Category from "@distilled.cloud/core/category";
+
+/**
+ * Unknown UniFi Network error — returned when a failed response's HTTP
+ * status has no mapped error class, OR (given the spec's total silence on
+ * error shapes) as the fallback for any status this SDK has not been told
+ * about by a real failure yet. Carries the raw body for later cataloging.
+ */
+export class UnknownUnifiNetworkError extends Schema.TaggedError<UnknownUnifiNetworkError>()(
+  "UnknownUnifiNetworkError",
+  {
+    code: Schema.optional(Schema.String),
+    message: Schema.optional(Schema.String),
+    body: Schema.Unknown,
+  },
+).pipe(Category.withServerError) {}
+
+/** Schema parse error wrapper. */
+export class UnifiNetworkParseError extends Schema.TaggedError<UnifiNetworkParseError>()(
+  "UnifiNetworkParseError",
+  {
+    body: Schema.Unknown,
+    cause: Schema.Unknown,
+  },
+).pipe(Category.withParseError) {}
+
+/**
+ * Errors any UniFi Network operation may surface in addition to the shared
+ * HTTP status errors.
+ */
+export type ClientErrors = UnknownUnifiNetworkError | UnifiNetworkParseError;
+
+/**
+ * Default UniFi Network operation errors.
+ *
+ * EVERY operation carries the whole set — the spec types no failure at all,
+ * per-operation or wildcard, so the error channel says a `404` (site or
+ * object not found), `400` (a malformed whole-object PUT — see the
+ * package README) or `409` is possible on any call rather than pretending
+ * only the statuses core marks "default" (401/429/5xx) can happen.
+ */
+export type DefaultErrors =
+  | CoreDefaultErrors
+  | CoreBadRequest
+  | CoreForbidden
+  | CoreNotFound
+  | CoreConflict
+  | CoreUnprocessableEntity
+  | ClientErrors;

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @distilled.cloud/unifi-network — UniFi Network Integration API SDK for
+ * Effect.
+ *
+ * `./services` is generated by `scripts/generate.ts` from the Smithy models
+ * in `.generated-specs` (written by `scripts/convert.ts` from the OpenAPI
+ * document at `specs/spec-mirror-unifi-network/specs/openapi.json`).
+ * Everything else in this folder is hand-written.
+ *
+ * One module per UniFi Network API tag (Sites, UniFi Devices, Clients,
+ * Networks, WiFi Broadcasts, Hotspot, Firewall, Access Control, Switching,
+ * DNS Policies, Traffic Matching Lists, Supporting Resources, Application
+ * Info) — the same split the API reference uses.
+ *
+ * ⛔ READ THE PACKAGE README before writing a Resource against this SDK: it
+ * documents traps this SDK does NOT paper over on purpose (whole-object PUT
+ * semantics, ordering endpoints, adopt-only objects, hardware-affecting
+ * writes) — this package is the API walk-down, not a provider.
+ *
+ * @example
+ * ```ts
+ * import * as UnifiNetwork from "@distilled.cloud/unifi-network";
+ *
+ * const { data: sites } = yield* UnifiNetwork.Services.sites.getSiteOverviewPage({});
+ * ```
+ */
+export * from "./credentials.ts";
+export * from "./errors.ts";
+export * as T from "./traits.ts";
+export {
+  UnifiNetworkProtocol,
+  type UnifiNetworkOpError,
+  type UnifiNetworkOpContext,
+} from "./protocol.ts";
+export * as Retry from "./retry.ts";
+export * as Services from "./services/index.ts";

package/src/protocol.ts

@@ -0,0 +1,86 @@
+/**
+ * UnifiNetworkProtocol — the shared header-auth REST protocol instantiated
+ * for the UniFi Network Integration API.
+ *
+ * The spec's `info.description` is empty and its `components` carries no
+ * `securitySchemes` — this package cannot generate its auth from the
+ * document, unlike almost every other OpenAPI-sourced package here. The
+ * `X-API-KEY` header is sourced from Ubiquiti's own Integration API guide;
+ * see the warning in `src/credentials.ts`.
+ *
+ * Response envelope: list endpoints return `{ count, data, limit, offset,
+ * totalCount }` (offset pagination — see `scripts/convert.ts` for why no
+ * `smithy.api#paginated` trait is stamped yet); single-resource endpoints
+ * return the object directly; mutations return the created/updated object
+ * (`200`/`201`), never `204`.
+ *
+ * FAILURE ENVELOPE IS UNKNOWN: no operation in the spec documents an error
+ * response, so there is no field to read a machine-readable code or message
+ * from (`errorEnvelope` below always returns undefined, meaning every
+ * failure falls through to the protocol's raw-text / `HTTP <status>`
+ * default and `unknownError`). Replace this the first time a real console
+ * failure is captured and its body shape is known.
+ */
+import * as Effect from "effect/Effect";
+import type * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type * as HttpClientError from "effect/unstable/http/HttpClientError";
+import type * as API from "@distilled.cloud/core/api";
+import type { ConfigError } from "@distilled.cloud/core/errors";
+import {
+  makeRestProtocol,
+  type RestErrorEnvelope,
+} from "@distilled.cloud/core/protocol-rest";
+import { Credentials, type Config } from "./credentials.ts";
+import { UnknownUnifiNetworkError, type DefaultErrors } from "./errors.ts";
+
+/**
+ * Error channel shared by every generated UniFi Network operation. Generated
+ * service files annotate operations with `API.OperationMethod<I, O,
+ * UnifiNetworkOpError, UnifiNetworkOpContext>` explicitly so the compiler
+ * never infers these back out of the schema generics.
+ */
+export type UnifiNetworkOpError =
+  | DefaultErrors
+  | ConfigError
+  | HttpClientError.HttpClientError;
+
+/** Context (requirements) shared by every generated UniFi Network operation. */
+export type UnifiNetworkOpContext = Credentials | HttpClient.HttpClient;
+
+/**
+ * No documented failure envelope to parse (see module docs) — every failure
+ * falls through to the protocol's status-derived default and
+ * {@link UnknownUnifiNetworkError}.
+ */
+const errorEnvelope = (_body: unknown): RestErrorEnvelope | undefined =>
+  undefined;
+
+export const UnifiNetworkProtocol: Layer.Layer<API.Protocol> =
+  makeRestProtocol<Config>({
+    // Resolved on the CALLING fiber per request (the layer is memoized per
+    // process); the Credentials service holds an effect, so a key rotated
+    // between calls is picked up without rebuilding the layer.
+    credentials: Effect.gen(function* () {
+      const resolve = yield* Credentials;
+      return yield* resolve;
+    }),
+    baseUrl: (creds) => creds.apiBaseUrl,
+    headers: (creds) => ({
+      "X-API-KEY": Redacted.value(creds.apiKey),
+      Accept: "application/json",
+    }),
+    errorEnvelope,
+    unknownError: ({ code, message, body }) =>
+      new UnknownUnifiNetworkError({
+        code:
+          typeof code === "string"
+            ? code
+            : code !== undefined
+              ? String(code)
+              : undefined,
+        message,
+        body,
+      }),
+  });

package/src/retry.ts

@@ -0,0 +1,83 @@
+/**
+ * UniFi Network retry surface — a veneer over `@distilled.cloud/core/retry`.
+ *
+ * The `Retry` service tag is threaded into every generated operation via
+ * `API.make({ retry: Retry })`, so a caller-installed policy applies to all
+ * UniFi Network calls below it and core's `makeDefault` is the fallback when
+ * none is provided.
+ *
+ * No operation in the spec documents a 429 response (see `src/errors.ts`),
+ * so whether a console rate-limits at all — and whether it sends
+ * `Retry-After` — is unconfirmed. `TooManyRequests` is wired through core's
+ * shared status map regardless (a console-side reverse proxy or the cloud
+ * connector could still emit one), and the default policy's capped backoff
+ * applies when no server hint is present.
+ *
+ * @example
+ * ```ts
+ * import * as UnifiNetwork from "@distilled.cloud/unifi-network";
+ *
+ * myEffect.pipe(UnifiNetwork.Retry.transient);
+ * ```
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Retries from "@distilled.cloud/core/retry";
+
+export type Options = Retries.Options;
+export type Factory = Retries.Factory;
+export type Policy = Retries.Policy;
+
+/** Context tag for configuring retry behavior of UniFi Network API calls. */
+export class Retry extends Context.Service<Retry, Policy>()(
+  "UnifiNetworkRetry",
+) {}
+
+/** Provides a custom retry policy to every UniFi Network API call below it. */
+export const policy: {
+  (
+    options: Options,
+  ): <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, Exclude<R, Retry>>;
+  (
+    factory: Factory,
+  ): <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, Exclude<R, Retry>>;
+} = (optionsOrFactory: Options | Factory) =>
+  Effect.provide(Layer.succeed(Retry, optionsOrFactory));
+
+/** Disables all automatic retries. */
+export const none: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, E, Exclude<R, Retry>> = Effect.provide(
+  Layer.succeed(Retry, { while: () => false }),
+);
+
+/**
+ * The default retry policy (core's): transient/throttling/retryable errors,
+ * capped exponential backoff with jitter, server `retryAfter` hints honored
+ * with precedence.
+ */
+export const makeDefault: Factory = Retries.makeDefault;
+
+export const jittered = Retries.jittered;
+export const capped = Retries.capped;
+
+/** Retry options that retry all throttling errors indefinitely. */
+export const throttlingOptions: Options = Retries.throttlingOptions;
+
+/** Retries all throttling errors indefinitely (honoring server hints). */
+export const throttling: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, E, Exclude<R, Retry>> = policy(Retries.throttlingFactory);
+
+/** Retry options that retry all transient errors indefinitely. */
+export const transientOptions: Options = Retries.transientOptions;
+
+/** Retries all transient errors indefinitely (honoring server hints). */
+export const transient: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, E, Exclude<R, Retry>> = policy(Retries.transientFactory);