Integration Toolkit

Placeholder content. Point externalUrl at the real repository when it exists — the gallery card and this page both use it.

Why extract it

The dashboard's sync layer solved the same problem over and over: fetch from an API that will eventually change shape, validate it, normalize it, and write it without creating duplicates. That pattern isn't personal — it's the boring middle of every integration anyone writes.

The interface

Every source is one object:

export const source: SourceDefinition = {
  key: "example",
  displayName: "Example",
  schedule: "hourly",
  async sync(ctx) {
    const payload = await fetchSince(ctx.since);
    const rows = Schema.array().parse(payload);
    return ctx.upsert(rows);
  },
};

Design rules

• Validate at the boundary. Unofficial and undocumented APIs change without notice; a schema violation should surface loudly rather than write a half-empty row.
• Never drop silently. A failed parse becomes a visible error, not a skipped record.
• Watermarks, not full scans. Each run reports the point it reached so the next one starts there.

Status

Placeholder — replace with real installation instructions and version notes.