feat(sdk): Effect v4 + @effect/openapi-generator; typed pf.api & example ladder

Drop Orval for the first-party @effect/openapi-generator (OpenAPI 3.1 ->
Effect Schema + a typed HttpClient client) and bump effect 3.19 ->
4.0.0-beta.98. Port the hand-written surfaces to the v4 API (Result over
Either, Context.Service, Codec, Literals/Union arrays, Stream/Schedule/
Effect renames). Transport (CA-pinning fetch) and the reconnecting SSE
source are kept intact.

Make the SDK approachable for non-Effect users:
- Add pf.api.* on the Promise facade: the generated client surfaced as
  typed, Promise-native methods (await pf.api.listPairedClients()), so REST
  calls are autocompleted and checked instead of stringly-typed
  pf.request(method, path, body) + `as` casts. Zero-drift veneer over
  make(httpClient), backed by the same pinning fetch. pf.request stays as
  the untyped escape hatch.
- Re-tier examples into a 1-4 complexity ladder, rewritten onto pf.api.*
  (the typed payloads caught a wrong `launch` shape in provider-sync);
  the Effect example is labelled advanced. Add examples/ to tsconfig so
  they are typechecked (stops rot).

typecheck + 19 tests green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

sdk/examples/couch-preset.effect.ts

@@ -1,6 +1,11 @@
-// The RFC §7 quickstart, Effect-native: when the living-room TV starts a stream, apply a
-// display preset — a composed, typed, interruptible program.
-import { Effect, Stream } from "effect";
+// ── Example 4/4 · ADVANCED, Effect-native ───────────────────────────────────────────────────
+// You do NOT need this to use the SDK — examples 1–3 (the plain Promise `connect()` facade) cover
+// most automation. Reach for `@punktfunk/host/effect` only when you're composing Effect programs
+// and want the event stream, typed errors, and structured interruption as first-class values.
+//
+// Here: when the living-room TV starts a stream, apply a display preset — as a single composed,
+// typed, interruptible program (a `Stream` of events piped into a request, provided a live layer).
+import { Cause, Effect, Stream } from "effect";
 import { events, PunktfunkHost, PunktfunkHostLive } from "../src/effect.js";
 
 const program = Effect.gen(function* () {
@@ -12,7 +17,11 @@ const program = Effect.gen(function* () {
 		Stream.runForEach(() =>
 			pf
 				.request("PUT", "/display/settings", { mode: "preset", preset: "couch" })
-				.pipe(Effect.catchAll((e) => Effect.logWarning(`preset failed: ${e}`))),
+				.pipe(
+					Effect.catchCause((cause) =>
+						Effect.logWarning(`preset failed: ${Cause.pretty(cause)}`),
+					),
+				),
 		),
 	);
 });

sdk/examples/notify-pairing.ts

@@ -1,5 +1,7 @@
-// The flagship hook-with-a-decision pattern (Promise facade): watch pairing requests, notify,
-// and approve/deny THROUGH the API — asynchronously, the punktfunk way (hooks never veto).
+// ── Example 2/4 · event → decision ──────────────────────────────────────────────────────────
+// The flagship pattern: watch pairing requests, notify yourself, and approve/deny THROUGH the
+// typed API — asynchronously, the punktfunk way (hooks never veto). Every call is checked and
+// autocompleted; no hand-written paths, no casts.
 import { connect } from "../src/index.js";
 
 const pf = await connect();
@@ -7,9 +9,13 @@ console.log("watching for pairing requests…");
 
 pf.events.on("pairing.pending", async (e) => {
 	console.log(`pairing request: ${e.device.name} (${e.device.fingerprint})`);
-	// Wire your real notifier here (ntfy, Pushover, Home Assistant, …), then decide:
-	//   const pending = await pf.request("GET", "/native/pending") as { id: number }[];
-	//   await pf.request("POST", `/native/pending/${pending[0].id}/approve`);
+
+	// Wire your real notifier here (ntfy, Pushover, Home Assistant, …). Then decide by calling
+	// the API — find the pending device by fingerprint and approve it (send `{}` to keep the
+	// name it knocked with):
+	const pending = await pf.api.listPendingDevices();
+	const match = pending.find((d) => d.fingerprint === e.device.fingerprint);
+	if (match) await pf.api.approvePendingDevice(String(match.id), { payload: {} });
 });
 pf.events.on("pairing.completed", (e) => console.log(`paired: ${e.device.name}`));
 pf.events.on("pairing.denied", (e) => console.log(`denied: ${e.device.name}`));

sdk/examples/provider-sync.ts

@@ -1,6 +1,10 @@
+// ── Example 3/4 · typed bulk REST ───────────────────────────────────────────────────────────
 // The external game-library provider pattern (RFC §8): compute your desired title list and
-// declaratively PUT it — the host diffs by your `external_id`, keeps host ids stable across
-// syncs, drops orphans, and never touches manual entries. Uninstall = one DELETE.
+// declaratively reconcile it — the host diffs by your `external_id`, keeps host ids stable across
+// syncs, drops orphans, and never touches manual entries. Uninstall = one call.
+//
+// Note how the typed `payload` catches shape mistakes at compile time: `launch` is a
+// `LaunchSpec` — `{ kind, value }`, not a bare command string.
 import { connect } from "../src/index.js";
 
 const PROVIDER = "romm"; // your punktfunk-plugin-* name
@@ -12,15 +16,23 @@ pf.events.on("library.changed", (e) => {
 
 // Fetch your source of truth (a ROM manager, itch.io, a curated list…), then reconcile:
 const desired = [
-	{ external_id: "rom-1", title: "Chrono Trigger", launch: { command: "retroarch ..." } },
-	{ external_id: "rom-2", title: "Super Metroid", launch: { command: "retroarch ..." } },
+	{
+		external_id: "rom-1",
+		title: "Chrono Trigger",
+		launch: { kind: "command", value: "retroarch -L snes9x chrono-trigger.sfc" },
+	},
+	{
+		external_id: "rom-2",
+		title: "Super Metroid",
+		launch: { kind: "command", value: "retroarch -L snes9x super-metroid.sfc" },
+	},
 ];
-const entries = (await pf.request("PUT", `/library/provider/${PROVIDER}`, desired)) as {
-	id: string;
-	title: string;
-}[];
-console.log(`synced ${entries.length} titles:`, entries.map((e) => `${e.title} (custom:${e.id})`));
+const entries = await pf.api.reconcileProviderEntries(PROVIDER, { payload: desired });
+console.log(
+	`synced ${entries.length} titles:`,
+	entries.map((e) => `${e.title} (custom:${e.id})`),
+);
 
 // …run on a schedule, or keep watching your source. Clean uninstall:
-//   await pf.request("DELETE", `/library/provider/${PROVIDER}`);
+//   await pf.api.deleteProviderEntries(PROVIDER);
 pf.close();

sdk/examples/tail-events.ts

@@ -1,12 +1,17 @@
-// Tail the host's lifecycle events — the SDK "hello world" (Promise facade).
+// ── Example 1/4 · the "hello world" ─────────────────────────────────────────────────────────
+// Connect, make one typed API call, and tail the host's lifecycle events. No Effect knowledge
+// needed — `connect()` returns a plain Promise client.
 //
 //   bun examples/tail-events.ts          (on the host box: zero config)
 //   PUNKTFUNK_MGMT_URL=… PUNKTFUNK_MGMT_TOKEN=… bun examples/tail-events.ts
 import { connect } from "../src/index.js";
 
 const pf = await connect();
-const host = (await pf.request("GET", "/host")) as { hostname?: string };
-console.log(`connected to ${host.hostname ?? "host"} — tailing events (^C to stop)`);
+
+// `pf.api.*` is the typed front door: `host` is a fully-typed HostInfo — no cast, autocomplete
+// for every field.
+const host = await pf.api.getHostInfo();
+console.log(`connected to ${host.hostname} — tailing events (^C to stop)`);
 
 pf.events.on("*", (e) => console.log(`[${e.seq}] ${e.kind}`, JSON.stringify(e)));
 pf.events.on("unknown", (e) => console.log("[unknown kind]", JSON.stringify(e)));