SourceExtension
A complete source: what it is, and what it does.
Extends
Section titled “Extends”Type Parameters
Section titled “Type Parameters”| Type Parameter | Default type | Description |
|---|---|---|
C | Record<string, unknown> | The shape of the source’s typed ctx.config preferences. |
Properties
Section titled “Properties”| Property | Type | Description | Inherited from |
|---|---|---|---|
auth? | Record<string, unknown> | A declared authorization strategy, for sources that hold one. | SourceManifest.auth |
author | string | Who wrote the source. | SourceManifest.author |
available? | boolean | Whether the source is offered in the marketplace. | SourceManifest.available |
config? | Record<string, ManifestConfigField> | The preference fields shown in the setup wizard. Preferences only — no credentials. | SourceManifest.config |
cursor | | "date" | "idSet" | "none" | "highWaterId" | "opaqueToken" | "snapshot" | "mtime" | "rowid" | How the source remembers where it stopped — none, date, idSet, highWaterId. | SourceManifest.cursor |
description | string | One-line directory description. | SourceManifest.description |
egress | readonly string[] | The hosts this source may reach. Host-exact, and enforced at run time — a host absent here is unreachable, not merely undeclared. | SourceManifest.egress |
egressNote? | string | Why the egress list looks the way it does, when that needs saying. | SourceManifest.egressNote |
egressNotFetched? | readonly string[] | Hosts that appear in content but are never fetched. | SourceManifest.egressNotFetched |
fanOut? | string | The config field this source fans out over — one run covers every value in it. Names a key of SourceManifest.config, so fanOut: 'feeds' means the user’s feeds list is the unit of expansion. Declared as Record<string, unknown> until 3.3.0, which described nothing any catalog wrote: all seven uses are a bare key name. | SourceManifest.fanOut |
formatting? | "reformat" | "verbatim" | Whether the platform reformats this source’s text, or leaves it verbatim. | SourceManifest.formatting |
generated? | boolean | Marks the file as an artifact of toSourceManifest, not a hand-written document. Every generated manifest carries it; nothing reads it but a person. | SourceManifest.generated |
historyReach? | HistoryReach | How far back the source can reach, when that is bounded by the upstream. | SourceManifest.historyReach |
icon | string | A single emoji or an HTTPS URL to a square icon. | SourceManifest.icon |
id | string | Stable source-type id; pattern ^[a-z0-9-]+$. | SourceManifest.id |
ingest | "append" | "upsert" | How documents enter the library. Every source built so far is append. | SourceManifest.ingest |
kind | "scheduled-sync" | "on-demand-fetch" | "on-demand-query" | What kind of source this is. Every source built so far is scheduled-sync. | SourceManifest.kind |
name | string | Human-readable display name. | SourceManifest.name |
needsBrowser | boolean | Whether the source requires a Playwright browser. | SourceManifest.needsBrowser |
runsIn | "cloud" | "mac" | Where the source runs by default — cloud or mac. | SourceManifest.runsIn |
runtime? | string | deployed when the source runs on its own in the hosted runtime. | SourceManifest.runtime |
schedule | | "every 30 minutes" | "every 1 hour" | "every 2 hours" | "every 4 hours" | "every 6 hours" | "every 12 hours" | "daily" | "weekly" | "monthly" | "yearly" | "on demand" | Human-readable cadence, one of the recognised schedules. | SourceManifest.schedule |
secrets? | readonly string[] | Credential names the source reads through ctx.secret(). | SourceManifest.secrets |
status | string | Whether the source is built (implemented) or still a declaration. | SourceManifest.status |
transport | "feed" | "scrape" | "api" | "browser" | "local" | How the source reaches upstream — feed, api, scrape, browser, local. | SourceManifest.transport |
version | string | Semver version string. | SourceManifest.version |
Methods
Section titled “Methods”sync()
Section titled “sync()”sync(ctx: SourceContext<C>): Promise<SourceSyncResult | Document[]>;The batch entry point. Fetches new content and returns documents to
index, optionally with a new cursor. May return a bare Document[]
for convenience. Throw a plain Error to fail the run (the Mac app records
the error and retries next tick).
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
ctx | SourceContext<C> |
Returns
Section titled “Returns”Promise<SourceSyncResult | Document[]>