Building a Source Adapter

You can connect anything to Trove by building a source adapter — one defineSource call in extension.ts that fetches content from an upstream and returns documents for your knowledge base. Trove stores, indexes, and searches them.

This guide has moved

The full source-adapter documentation now lives in the Sources series. This page is a short pointer kept in place so existing links don’t break.

Start here

• Sources Overview — what a source is, and the collect-vs-serve framing.
• Quickstart — build your first source adapter in about 10 minutes with a real public feed.
• SDK Reference — the @ontrove/extend/source API: TroveSource, sync(ctx), the ctx object, the document shape, and audio transcription.
• Source Manifest Reference — every field you declare, and why the manifest is generated.
• Cursors and Feeds — multi-feed sources, cursor types, and the cursor compare-and-swap protocol.

The contract, in one breath

Your sync(ctx) returns an array of documents. Each has a stable id, some text (or an audioUrl for transcription), and optional title, url, author, and date. Trove deduplicates by id, tracks a per-feed cursor, embeds and indexes the text, and serves it to Claude.

extension.ts

import { defineSource } from "@ontrove/extend/source";

export default defineSource({
  // …identity, the four type-system fields, runsIn, schedule, egress…
  async sync(ctx) {
    const res = await ctx.fetch(ctx.config.feedUrl as string);
    return parseFeed(await res.text()).map((item) => ({
      id: item.guid,
      title: item.title,
      text: item.body,
      url: item.link,
      author: item.author,
      date: item.published,
    }));
  },
});

If you want to push documents directly over the wire from your own client, see the Sync API and the ingestDocuments mutation that source adapters map onto.