@ajnart/self-host-testkit 0.0.0-stage → 1.3.0

package/examples/homarr-sonarr.mjs

@@ -0,0 +1,66 @@
+import { withPair } from "@ajnart/self-host-testkit";
+
+const order = process.argv[2] ?? "consumer-first";
+if (order !== "consumer-first" && order !== "target-first") {
+	throw new Error("Choose consumer-first or target-first.");
+}
+
+await withPair(
+	"homarr",
+	"sonarr",
+	async (pair) => {
+		if ((await pair.inspect()).outcome !== "complete") {
+			throw new Error(
+				"Production Setup/Link has a failed or Manual prerequisite.",
+			);
+		}
+		const response = await fetch(`${pair.target.url}/api/v3/system/status`, {
+			headers: { "X-Api-Key": await pair.target.getApiKey() },
+			signal: AbortSignal.timeout(10_000),
+		});
+		if (!response.ok || (await response.json()).appName !== "Sonarr") {
+			throw new Error("Sonarr identity did not authenticate.");
+		}
+		const integrationId = await pair.consumer.getApiKey("linked_sonarr");
+		const apiKey = await pair.consumer.getApiKey();
+		const snapshot = async () => {
+			const input = encodeURIComponent(
+				JSON.stringify({ json: { integrationId } }),
+			);
+			const result = await fetch(
+				`${pair.consumer.url}/api/trpc/widget.stats.snapshot?input=${input}`,
+				{
+					headers: { ApiKey: apiKey },
+					signal: AbortSignal.timeout(10_000),
+				},
+			);
+			if (!result.ok) throw new Error("Homarr Stats could not be read.");
+			const envelope = await result.json();
+			const sample = envelope.result?.data?.json;
+			if (
+				envelope.error ||
+				!sample ||
+				sample.error !== false ||
+				sample.stale !== false ||
+				!Number.isFinite(sample.updatedAt) ||
+				sample.updatedAt <= 0 ||
+				!["shows", "downloaded", "missing", "queued"].every(
+					(key) =>
+						Number.isInteger(sample.values?.[key]) && sample.values[key] >= 0,
+				)
+			) {
+				throw new Error("Homarr did not return meaningful Sonarr Stats.");
+			}
+			return sample.updatedAt;
+		};
+		const before = await snapshot();
+		if (
+			(await pair.setup("homarr")).outcome !== "complete" ||
+			(await snapshot()) <= before
+		) {
+			throw new Error("Production Link verification did not advance Stats.");
+		}
+		console.log("Production Homarr/Sonarr Link and advancing Stats verified.");
+	},
+	{ order },
+);

package/examples/sonarr.mjs

@@ -0,0 +1,15 @@
+import { withApp } from "@ajnart/self-host-testkit";
+
+await withApp("sonarr", async (sonarr) => {
+	const response = await fetch(`${sonarr.url}/api/v3/system/status`, {
+		headers: { "X-Api-Key": await sonarr.getApiKey() },
+		signal: AbortSignal.timeout(10_000),
+	});
+	if (!response.ok)
+		throw new Error("Sonarr rejected the authenticated request.");
+	const status = await response.json();
+	if (status.appName !== "Sonarr" || typeof status.version !== "string") {
+		throw new Error("Sonarr returned an unexpected identity.");
+	}
+	console.log(`Connected to Sonarr ${status.version}.`);
+});

package/index.d.mts

@@ -0,0 +1,102 @@
+import { type TestkitStartupReason } from "./reasons.mjs";
+export type { TestkitStartupReason } from "./reasons.mjs";
+export interface Credentials {
+    readonly username: string;
+    readonly password: string;
+    readonly email: string;
+    readonly apiKey: string;
+}
+export interface AppInfo {
+    readonly id: string;
+    readonly url: string;
+    readonly image: string;
+    readonly imageId: string;
+    readonly repoDigests: string[];
+}
+export interface App {
+    readonly url: string;
+    readonly recoveryPath?: string;
+    getApiKey(name?: string): Promise<string>;
+    credentials(): Promise<Credentials>;
+    info(): Promise<AppInfo>;
+    close(): Promise<void>;
+}
+export interface SpinupOptions {
+    image?: string;
+}
+export interface SelfHost {
+    readonly recoveryPath?: string;
+    spinup(app: string, options?: SpinupOptions): Promise<App>;
+    spinupPair(consumer: string, target: string, options: PairOptions): Promise<Pair>;
+    close(): Promise<void>;
+}
+export interface PairOptions {
+    order: "consumer-first" | "target-first";
+    images?: Readonly<Record<string, string>>;
+    sonarrFilterWitness?: true;
+}
+export interface SonarrFilterWitness {
+    readonly kind: "sonarr-custom-filter-v1";
+    readonly objectId: number;
+    readonly contentSha256: string;
+}
+declare const pairStates: readonly ["running", "exited", "created", "restarting", "paused", "missing", "unknown", "dead", "removing", "degraded"];
+export type PairAppState = (typeof pairStates)[number];
+export interface PairAppStatus {
+    readonly id: string;
+    readonly url: string;
+    readonly installed: boolean;
+    readonly state: PairAppState;
+    readonly setup: "ok" | "manual" | "incomplete" | "pending";
+    readonly steps: ReadonlyArray<{
+        readonly id: string;
+        readonly status: "ok" | "manual" | "fail" | "skip";
+        readonly verified: boolean;
+    }>;
+}
+export type PairInspection = {
+    readonly link: string;
+    readonly apps: readonly PairAppStatus[];
+} & ({
+    readonly outcome: "complete";
+    readonly reason: "verified";
+} | {
+    readonly outcome: "manual" | "failed";
+    readonly reason: "setup";
+} | {
+    readonly outcome: "prerequisite";
+    readonly reason: "absent" | "unready" | "not-run";
+});
+export type PairApp = Omit<App, "close">;
+export interface Pair {
+    readonly consumer: PairApp;
+    readonly target: PairApp;
+    readonly initial: PairInspection;
+    readonly recoveryPath?: string;
+    inspect(): Promise<PairInspection>;
+    setup(app?: string): Promise<PairInspection>;
+    remove(app: string): Promise<PairInspection>;
+    install(app: string): Promise<PairInspection>;
+    createSonarrFilterWitness(): Promise<SonarrFilterWitness>;
+    readSonarrFilterWitness(): Promise<SonarrFilterWitness>;
+    close(): Promise<void>;
+}
+export interface SelfHostOptions {
+    binary?: string;
+    timeoutMs?: number;
+    manifest?: string;
+}
+export type TestkitErrorCode = "PROTOCOL" | "STATE" | "START" | "CREDENTIALS" | "INFO" | "CLEANUP" | "TIMEOUT" | "TRANSPORT" | "OPERATION" | "CANCELED" | "BINARY";
+export declare class TestkitError extends Error {
+    readonly code: TestkitErrorCode;
+    readonly reason: TestkitStartupReason | undefined;
+    readonly cleanupFailed: boolean;
+    readonly recoveryPath?: string;
+    constructor(code: TestkitErrorCode, reason?: TestkitStartupReason, recoveryPath?: string, cleanupFailed?: boolean);
+}
+export declare function createSelfHost(options?: SelfHostOptions): SelfHost;
+export interface ScopedOptions {
+    onCleanupError?: (error: TestkitError) => void | Promise<void>;
+}
+export declare function withApp<T>(app: string, callback: (app: App) => T | Promise<T>, options?: SelfHostOptions & SpinupOptions & ScopedOptions): Promise<T>;
+export declare function withPair<T>(consumer: string, target: string, callback: (pair: Pair) => T | Promise<T>, options: SelfHostOptions & PairOptions & ScopedOptions): Promise<T>;