unom/punktfunk
1
0
Fork 0
Code Issues Pull Requests Actions 13 Packages Projects Releases 25 Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Enrico Bühler
2026-07-17 12:40:04 +02:00
parent 27a5d8daac
commit f012ebbcba
19 changed files with 1645 additions and 1974 deletions
Download Patch File Download Diff File Expand all files Collapse all files
sdk/examples/provider-sync.ts
+22 -10
View File
@@ -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();