@ontrove/sdk 0.1.0 → 0.3.0

package/dist/runtime.js

@@ -1,16 +1,16 @@
 /**
- * The local-run harness — what makes `trove connector dev` / `trove connector test`
- * work (connectors/sdk-reference; connectors/cursors-and-sources).
+ * The local-run harness — what makes `trove source dev` / `trove source test`
+ * work (sources/sdk-reference; the cursors guide).
  *
- * {@link runConnector} builds a {@link ConnectorContext} from a `{ config, cursor }`
+ * {@link runSource} builds a {@link SourceContext} from a `{ config, cursor }`
  * spec, invokes `sync(ctx)`, then normalizes and validates the result: it accepts
- * either a `ConnectorSyncResult` or a bare `ConnectorDocument[]`, deduplicates by
- * `id` (first occurrence wins, matching server-side `(source, id)` dedup), and
+ * either a `SourceSyncResult` or a bare `SourceDocument[]`, deduplicates by
+ * `id` (first occurrence wins, matching server-side `(feed, id)` dedup), and
  * validates every document's required fields, surfacing problems clearly instead
  * of pushing a malformed payload to the cloud.
  *
  * It is the symmetric sibling of `@ontrove/mcp`'s `dispatch`/`toFetchHandler`: that
- * runs a tool call end-to-end without the hosted runtime; this runs a connector
+ * runs a tool call end-to-end without the hosted runtime; this runs a source
  * sync end-to-end without the Mac app sync engine.
  *
  * @module
@@ -45,7 +45,7 @@ function validateDocument(doc, index) {
     }
 }
 /**
- * Normalize a `sync` return value to a {@link ConnectorSyncResult}, accepting a
+ * Normalize a `sync` return value to a {@link SourceSyncResult}, accepting a
  * bare document array for convenience.
  *
  * @param value - The raw `sync` return value.
@@ -65,7 +65,7 @@ function normalizeResult(value) {
 }
 /**
  * Deduplicate documents by `id`, keeping the first occurrence (matching the
- * server's `(source, id)` dedup, which skips re-returned ids).
+ * server's `(feed, id)` dedup, which skips re-returned ids).
  *
  * @param documents - The validated documents.
  * @returns The deduped documents and the count dropped.
@@ -85,22 +85,22 @@ function dedup(documents) {
     return { unique, duplicatesSkipped };
 }
 /**
- * Run a connector's `sync` against a built `ctx` and collect/validate the result.
+ * Run a source's `sync` against a built `ctx` and collect/validate the result.
  *
- * This is the harness the CLI drives for `trove connector dev` / `trove connector
- * test`: it builds the {@link ConnectorContext} from `{ config, cursor }`, runs
+ * This is the harness the CLI drives for `trove source dev` / `trove source
+ * test`: it builds the {@link SourceContext} from `{ config, cursor }`, runs
  * `sync(ctx)`, normalizes a bare-array return, validates every document's
  * required fields (clear, indexed errors), and dedups by `id`. Errors thrown by
  * `sync` itself propagate unchanged so the CLI can report a failed run exactly as
  * the Mac app would.
  *
- * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
- * @param connector - The connector whose `sync` to run.
+ * @typeParam C - The shape of the source's typed `ctx.config` preferences.
+ * @param source - The source whose `sync` to run.
  * @param options - The `{ config, cursor }` spec plus test injection points.
  * @returns The validated, deduped {@link RunResult}.
  * @throws {Error} If `sync` throws, returns a malformed value, or a document fails validation.
  */
-export async function runConnector(connector, options = {}) {
+export async function runSource(source, options = {}) {
     const logs = [];
     const cursor = options.cursor ?? { type: 'none' };
     const fetchImpl = options.fetchImpl ?? ((url, init) => globalThis.fetch(url, init));
@@ -119,7 +119,7 @@ export async function runConnector(connector, options = {}) {
         },
         now,
     };
-    const raw = await connector.sync(ctx);
+    const raw = await source.sync(ctx);
     const result = normalizeResult(raw);
     result.documents.forEach(validateDocument);
     const { unique, duplicatesSkipped } = dedup(result.documents);

package/dist/types.d.ts

@@ -1,15 +1,17 @@
 /**
- * Public type surface for the `@ontrove/sdk` connector authoring library.
+ * Public type surface for the `@ontrove/sdk` source authoring library.
  *
- * These types describe the connector contract (see the connectors SDK reference
- * and the cursors-and-sources guide): a connector is
- * an object with a `sync(ctx)` method that fetches from a source and returns
- * documents to index. The SDK owns the document shape (which maps 1:1 onto the
+ * These types describe the source contract (see the sources SDK reference
+ * and the cursors guide on the docs site): a source is
+ * an object with a `sync(ctx)` method that fetches new content from the
+ * upstream system and returns documents to index. The SDK owns the document shape (which maps 1:1 onto the
  * `IngestDocumentInput` wire type), the typed `ctx` capability object, the
  * watermark/cursor model, and the local-run harness the CLI drives.
  *
- * It is the symmetric sibling of `@ontrove/mcp`: a connector returns documents to be
- * _stored_ (batch `sync`); an MCP server returns tool results to be _read live_.
+ * It is the symmetric sibling of `@ontrove/mcp` (the toolkit-authoring library —
+ * every toolkit runs as a full MCP server on Trove's cloud): a source returns
+ * documents to be _stored_ (batch `sync`); a toolkit's tools return results to
+ * be _read live_.
  *
  * @module
  */
@@ -17,9 +19,9 @@
  * The default content type Trove assigns a document when it omits `contentType`.
  * Mirrors the GraphQL `ContentType` enum surfaced on `IngestDocumentInput`.
  */
-export type ConnectorContentType = 'text' | 'transcript' | 'highlight' | 'bookmark';
+export type SourceContentType = 'text' | 'transcript' | 'highlight' | 'bookmark';
 /**
- * A single document a connector returns from `sync`. The fields map **1:1** onto
+ * A single document a source returns from `sync`. The fields map **1:1** onto
  * the GraphQL `IngestDocumentInput` the Mac app pushes via `ingestDocuments`:
  *
  * | SDK field     | `IngestDocumentInput` field |
@@ -35,15 +37,15 @@ export type ConnectorContentType = 'text' | 'transcript' | 'highlight' | 'bookma
  * | `metadata`    | `metadata` (JSON)           |
  * | `contentType` | `contentType` (ContentType) |
  *
- * Dedup is keyed on `(source, id)`: returning the same `id` twice is safe and is
+ * Dedup is keyed on `(feed, id)`: returning the same `id` twice is safe and is
  * skipped on the server, so `sync` can be idempotent and retried freely. At least
  * one of `text` or `audioUrl` must be present — an audio-only document triggers
  * transcription (Whisper), and the transcript becomes the document text.
  */
-export interface ConnectorDocument {
+export interface SourceDocument {
     /**
-     * The stable external identifier from the source system — the dedup key within
-     * the source. Maps to `IngestDocumentInput.externalId`. Use the native id (HN
+     * The stable external identifier from the upstream system — the dedup key
+     * within the feed. Maps to `IngestDocumentInput.externalId`. Use the native id (HN
      * `objectID`, RSS `guid`, Notion page id), never a value that changes between
      * runs.
      */
@@ -78,7 +80,7 @@ export interface ConnectorDocument {
     /** Array of string tags. Maps to `IngestDocumentInput.tags`. */
     tags?: string[];
     /**
-     * Arbitrary connector-specific JSON. Maps to `IngestDocumentInput.metadata`.
+     * Arbitrary source-specific JSON. Maps to `IngestDocumentInput.metadata`.
      * **Never** put credentials or auth headers here.
      */
     metadata?: Record<string, unknown>;
@@ -87,19 +89,19 @@ export interface ConnectorDocument {
      * `IngestDocumentInput.contentType`. Defaults to `text` (transcribed audio
      * becomes `transcript` automatically).
      */
-    contentType?: ConnectorContentType;
+    contentType?: SourceContentType;
 }
 /**
- * A typed watermark describing how a source resumes between syncs. The opaque
- * `Source.cursor` string is parsed into one of these (see the cursors-and-sources
- * guide, watermark types).
+ * A typed watermark describing how a feed resumes between syncs. The opaque
+ * `Feed.cursor` string is parsed into one of these (see the cursors guide,
+ * watermark types).
  *
- * - `date` — the source is time-ordered and supports "since &lt;date&gt;"
+ * - `date` — the feed is time-ordered and supports "since &lt;date&gt;"
  *   filtering (RSS, most APIs); the newest `value` you push becomes the next
  *   cursor.
- * - `idSet` — the source has monotonic ids but no reliable date filter; advance
+ * - `idSet` — the feed has monotonic ids but no reliable date filter; advance
  *   to the highest id seen (`max`), optionally tracking a recent id set.
- * - `none` — re-fetch everything each run and rely purely on `(source, id)`
+ * - `none` — re-fetch everything each run and rely purely on `(feed, id)`
  *   dedup. Always correct, just less efficient.
  */
 export type Watermark = {
@@ -113,35 +115,35 @@ export type Watermark = {
     readonly type: 'none';
 };
 /**
- * The result of a connector `sync`: the documents fetched this run and, optionally,
- * the watermark the source should advance to. A connector may also return a bare
- * `ConnectorDocument[]` for convenience — {@link runConnector} normalizes that to
+ * The result of a source `sync`: the documents fetched this run and, optionally,
+ * the watermark the feed should advance to. A source may also return a bare
+ * `SourceDocument[]` for convenience — {@link runSource} normalizes that to
  * `{ documents }` with no cursor change.
  */
-export interface ConnectorSyncResult {
+export interface SourceSyncResult {
     /** The documents fetched this run, mapping 1:1 onto `IngestDocumentInput`. */
-    documents: ConnectorDocument[];
+    documents: SourceDocument[];
     /**
-     * The watermark to advance the source cursor to. Omit (or return `{ type: 'none' }`)
+     * The watermark to advance the feed's cursor to. Omit (or return `{ type: 'none' }`)
      * to leave the cursor unchanged. The cloud only advances if the new value is
      * monotonically ahead (compare-and-swap).
      */
     cursor?: Watermark;
 }
 /**
- * The standard `fetch` signature the SDK exposes on {@link ConnectorContext.fetch}.
+ * The standard `fetch` signature the SDK exposes on {@link SourceContext.fetch}.
  * Matches the platform `fetch` so existing code ports unchanged.
  */
 export type FetchLike = (url: string | URL, init?: RequestInit) => Promise<Response>;
 /**
- * The single argument to `sync` — a capability object: everything a connector
+ * The single argument to `sync` — a capability object: everything a source
  * reaches the outside world through is on `ctx`. There is no ambient authority.
  *
  * `ctx.credentials` (Keychain-resolved auth material) and `ctx.browser` (a
- * Playwright browser for `needs_browser` connectors) are **PROPOSED**, not part
+ * Playwright browser for `needs_browser` sources) are **PROPOSED**, not part
  * of the shipped contract, and so are intentionally absent here.
  */
-export interface ConnectorContext<C = Record<string, unknown>> {
+export interface SourceContext<C = Record<string, unknown>> {
     /**
      * The user's preference values, keyed by the field names declared in
      * `manifest.json` `config`. **Preferences only — never credentials.** Feed
@@ -150,19 +152,19 @@ export interface ConnectorContext<C = Record<string, unknown>> {
      */
     readonly config: C;
     /**
-     * The source's current watermark (the position from the previous run), or
+     * The feed's current watermark (the position from the previous run), or
      * `{ type: 'none' }` on the first sync. Read-only — advance the cursor by
      * returning a new {@link Watermark} from `sync`, not by mutating this.
      */
     readonly cursor: Watermark;
     /**
      * Behaves like the standard `fetch`. Prefer `ctx.fetch` over global `fetch` —
-     * in the Mac app it routes through per-connector timeouts, retry, and
-     * rate-limit handling, surfacing failures in the connector's error log.
+     * in the Mac app it routes through per-source timeouts, retry, and
+     * rate-limit handling, surfacing failures in the source's error log.
      */
     fetch: FetchLike;
     /**
-     * Structured log entry, surfaced in the Mac app's connector logs and the
+     * Structured log entry, surfaced in the Mac app's source logs and the
      * `createSyncRun` audit record. Useful for reporting counts and progress.
      */
     log(...args: unknown[]): void;
@@ -173,16 +175,16 @@ export interface ConnectorContext<C = Record<string, unknown>> {
     now(): Date;
 }
 /**
- * The type a connector's default export satisfies. A connector is an object with
- * a `sync` method that fetches from its source and returns documents to index.
+ * The type a source's default export satisfies. A source is an object with
+ * a `sync` method that fetches new content and returns documents to index.
  *
- * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
+ * @typeParam C - The shape of the source's typed `ctx.config` preferences.
  *
  * @example
  * ```ts
- * import { defineConnector } from '@ontrove/sdk';
+ * import { defineSource } from '@ontrove/sdk';
  *
- * export default defineConnector({
+ * export default defineSource({
  *   async sync(ctx) {
  *     const res = await ctx.fetch(ctx.config.feedUrl as string);
  *     return parse(await res.text());
@@ -190,18 +192,18 @@ export interface ConnectorContext<C = Record<string, unknown>> {
  * });
  * ```
  */
-export interface TroveConnector<C = Record<string, unknown>> {
+export interface TroveSource<C = Record<string, unknown>> {
     /**
-     * The batch entry point. Fetches from the source and returns documents to
-     * index, optionally with a new cursor. May return a bare `ConnectorDocument[]`
+     * The batch entry point. Fetches new content and returns documents to
+     * index, optionally with a new cursor. May return a bare `SourceDocument[]`
      * for convenience. Throw a plain `Error` to fail the run (the Mac app records
      * the error and retries next tick).
      */
-    sync(ctx: ConnectorContext<C>): Promise<ConnectorSyncResult | ConnectorDocument[]>;
+    sync(ctx: SourceContext<C>): Promise<SourceSyncResult | SourceDocument[]>;
 }
 /**
  * A single field descriptor inside a manifest `config` object — describes one
- * preference input shown in the connector's setup wizard.
+ * preference input shown in the source's setup wizard.
  */
 export interface ManifestConfigField {
     /** Display label in the setup UI. */
@@ -212,12 +214,12 @@ export interface ManifestConfigField {
     placeholder?: string;
 }
 /**
- * A connector `manifest.json` — declares what the connector is, how often it runs,
+ * A source `manifest.json` — declares what the source is, how often it runs,
  * and which preference fields the user fills in during setup
- * (connectors/manifest reference).
+ * (sources/manifest reference).
  */
-export interface ConnectorManifest {
-    /** Stable connector-type id; pattern `^[a-z0-9-]+$`. Required. */
+export interface SourceManifest {
+    /** Stable source-type id; pattern `^[a-z0-9-]+$`. Required. */
     id: string;
     /** Human-readable display name. Required. */
     name: string;
@@ -227,24 +229,24 @@ export interface ConnectorManifest {
     icon?: string;
     /** Semver version string. Required. */
     version: string;
-    /** Who wrote the connector. */
+    /** Who wrote the source. */
     author?: string;
     /** Directory grouping — `reading`, `social`, `finance`, `dev`, `media`, etc. */
     category?: string;
     /**
      * Human-readable sync cadence — `"every 6 hours"`, `"daily"`, `"on demand"`, or
-     * `null` for a live-only connector. Optional (default: on demand).
+     * `null` for a live-only source. Optional (default: on demand).
      */
     schedule?: string | null;
     /** The preference fields shown in the setup wizard. Preferences only — no credentials. */
     config?: Record<string, ManifestConfigField>;
-    /** Whether the connector requires a Playwright browser. Default `false`. */
+    /** Whether the source requires a Playwright browser. Default `false`. */
     needs_browser?: boolean;
     /** What kind of source this is — `feed`, `account`, `files`, `api`. */
     kind?: string;
-    /** How the connector reaches the source — `http`, `browser`, `fs`. */
+    /** How the source reaches the upstream system — `http`, `browser`, `fs`. */
     transport?: string;
-    /** Default content type for documents this connector produces. */
-    document_semantics?: ConnectorContentType;
+    /** Default content type for documents this source produces. */
+    document_semantics?: SourceContentType;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1,15 +1,17 @@
 /**
- * Public type surface for the `@ontrove/sdk` connector authoring library.
+ * Public type surface for the `@ontrove/sdk` source authoring library.
  *
- * These types describe the connector contract (see the connectors SDK reference
- * and the cursors-and-sources guide): a connector is
- * an object with a `sync(ctx)` method that fetches from a source and returns
- * documents to index. The SDK owns the document shape (which maps 1:1 onto the
+ * These types describe the source contract (see the sources SDK reference
+ * and the cursors guide on the docs site): a source is
+ * an object with a `sync(ctx)` method that fetches new content from the
+ * upstream system and returns documents to index. The SDK owns the document shape (which maps 1:1 onto the
  * `IngestDocumentInput` wire type), the typed `ctx` capability object, the
  * watermark/cursor model, and the local-run harness the CLI drives.
  *
- * It is the symmetric sibling of `@ontrove/mcp`: a connector returns documents to be
- * _stored_ (batch `sync`); an MCP server returns tool results to be _read live_.
+ * It is the symmetric sibling of `@ontrove/mcp` (the toolkit-authoring library —
+ * every toolkit runs as a full MCP server on Trove's cloud): a source returns
+ * documents to be _stored_ (batch `sync`); a toolkit's tools return results to
+ * be _read live_.
  *
  * @module
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ontrove/sdk",
-  "version": "0.1.0",
-  "description": "Thin standard library for authoring Trove connectors — defineConnector, the sync(ctx) capability object, the document shape, the local-run harness, and manifest validation.",
+  "version": "0.3.0",
+  "description": "Thin standard library for authoring Trove sources — defineSource, the sync(ctx) capability object, the document shape, the local-run harness, and manifest validation.",
   "type": "module",
   "license": "MIT",
   "author": "Hollyburn Analytics Inc. <matt@hollyburnanalytics.com>",
@@ -14,7 +14,8 @@
   },
   "keywords": [
     "trove",
-    "connector",
+    "source",
+    "sync",
     "sdk",
     "knowledge-base",
     "ingestion",
@@ -31,7 +32,13 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist", "src", "CHANGELOG.md", "LICENSE", "README.md"],
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
   "sideEffects": false,
   "scripts": {
     "prepack": "tsc -p tsconfig.build.json",

package/src/define.ts

@@ -1,40 +1,35 @@
 /**
- * `defineConnector` — the single entry point for authoring a Trove connector
- * (connectors/sdk-reference). It is the symmetric sibling of `defineMcpServer`
+ * `defineSource` — the single entry point for authoring a Trove source
+ * (sources/sdk-reference). It is the symmetric sibling of `defineMcpServer`
  * in `@ontrove/mcp`.
  *
  * It is an identity function with light, eager validation: it confirms the value
- * is a connector object with a `sync` method, so a typo (`snyc`, a missing
+ * is a source object with a `sync` method, so a typo (`snyc`, a missing
  * `sync`, a non-function) fails at authoring/deploy time with a clear message
  * rather than at the first scheduled run. It does **not** execute `sync` — that is
- * {@link runConnector}'s job.
+ * {@link runSource}'s job.
  *
  * @module
  */
 
-import type {
-  ConnectorContext,
-  ConnectorDocument,
-  ConnectorSyncResult,
-  TroveConnector,
-} from './types.js';
+import type { SourceContext, SourceDocument, SourceSyncResult, TroveSource } from './types.js';
 
 /**
- * Validate and return a connector definition unchanged.
+ * Validate and return a source definition unchanged.
  *
- * Using `defineConnector(...)` (rather than a bare `satisfies TroveConnector`)
- * gives an eager runtime check: the CLI calls this when loading a connector
+ * Using `defineSource(...)` (rather than a bare `satisfies TroveSource`)
+ * gives an eager runtime check: the CLI calls this when loading a source
  * module so a malformed export is rejected before any sync runs. The returned
  * value is the same object, with full inferred types preserved.
  *
- * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
- * @param connector - The connector object to validate.
- * @returns The same connector object.
- * @throws {Error} If `connector` is not an object with a `sync` function.
+ * @typeParam C - The shape of the source's typed `ctx.config` preferences.
+ * @param source - The source object to validate.
+ * @returns The same source object.
+ * @throws {Error} If `source` is not an object with a `sync` function.
  *
  * @example
  * ```ts
- * export default defineConnector({
+ * export default defineSource({
  *   async sync(ctx) {
  *     const res = await ctx.fetch(ctx.config.feedUrl as string);
  *     return parseRss(await res.text());
@@ -42,29 +37,27 @@ import type {
  * });
  * ```
  */
-export function defineConnector<C = Record<string, unknown>>(
-  connector: TroveConnector<C>,
-): TroveConnector<C> {
-  if (connector === null || typeof connector !== 'object') {
-    throw new Error('defineConnector: expected a connector object with a `sync` method');
+export function defineSource<C = Record<string, unknown>>(source: TroveSource<C>): TroveSource<C> {
+  if (source === null || typeof source !== 'object') {
+    throw new Error('defineSource: expected a source object with a `sync` method');
   }
-  if (typeof (connector as { sync?: unknown }).sync !== 'function') {
-    throw new Error('defineConnector: connector must have a `sync(ctx)` function');
+  if (typeof (source as { sync?: unknown }).sync !== 'function') {
+    throw new Error('defineSource: source must have a `sync(ctx)` function');
   }
-  return connector;
+  return source;
 }
 
 /**
- * A connector authored inline as a single `sync` function, for the common case
- * where the connector has no other members. Equivalent to
- * `defineConnector({ sync })`.
+ * A source authored inline as a single `sync` function, for the common case
+ * where the source has no other members. Equivalent to
+ * `defineSource({ sync })`.
  *
- * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
- * @param sync - The connector's `sync(ctx)` implementation.
- * @returns A validated {@link TroveConnector} wrapping `sync`.
+ * @typeParam C - The shape of the source's typed `ctx.config` preferences.
+ * @param sync - The source's `sync(ctx)` implementation.
+ * @returns A validated {@link TroveSource} wrapping `sync`.
  */
 export function defineSync<C = Record<string, unknown>>(
-  sync: (ctx: ConnectorContext<C>) => Promise<ConnectorSyncResult | ConnectorDocument[]>,
-): TroveConnector<C> {
-  return defineConnector<C>({ sync });
+  sync: (ctx: SourceContext<C>) => Promise<SourceSyncResult | SourceDocument[]>,
+): TroveSource<C> {
+  return defineSource<C>({ sync });
 }

package/src/index.ts

@@ -1,19 +1,20 @@
 /**
- * `@ontrove/sdk` — the thin standard library for authoring **Trove connectors**.
- * You write a `sync(ctx)` that fetches from a source and returns documents; the
+ * `@ontrove/sdk` — the thin standard library for authoring **Trove sources**.
+ * You write a `sync(ctx)` that fetches new content and returns documents; the
  * SDK owns the document shape (which maps 1:1 onto `IngestDocumentInput`), the
  * typed `ctx` capability object, the watermark/cursor model, the local-run
  * harness the CLI drives, and manifest validation.
  *
- * It is the symmetric sibling of `@ontrove/mcp`: a connector returns documents to
- * be _stored_ (`defineConnector` + `sync`); an MCP server returns tool results to
- * be _read live_ (`defineMcpServer`).
+ * It is the symmetric sibling of `@ontrove/mcp`, the toolkit-authoring library
+ * (every toolkit runs as a full MCP server on Trove's cloud): a source returns
+ * documents to be _stored_ (`defineSource` + `sync`); a toolkit's tools return
+ * results to be _read live_ (`defineMcpServer`).
  *
  * @example
  * ```ts
- * import { defineConnector } from '@ontrove/sdk';
+ * import { defineSource } from '@ontrove/sdk';
  *
- * export default defineConnector({
+ * export default defineSource({
  *   async sync(ctx) {
  *     const res = await ctx.fetch('https://hn.algolia.com/api/v1/search?tags=front_page');
  *     const { hits } = await res.json();
@@ -33,25 +34,25 @@
  * @module
  */
 
-export { defineConnector, defineSync } from './define.js';
+export { defineSource, defineSync } from './define.js';
 export {
   isCredentialConfigKey,
   type ManifestValidationResult,
-  validateConnectorManifest,
+  validateSourceManifest,
 } from './manifest.js';
 export {
   type RunOptions,
   type RunResult,
-  runConnector,
+  runSource,
 } from './runtime.js';
 export type {
-  ConnectorContentType,
-  ConnectorContext,
-  ConnectorDocument,
-  ConnectorManifest,
-  ConnectorSyncResult,
   FetchLike,
   ManifestConfigField,
-  TroveConnector,
+  SourceContentType,
+  SourceContext,
+  SourceDocument,
+  SourceManifest,
+  SourceSyncResult,
+  TroveSource,
   Watermark,
 } from './types.js';

package/src/manifest.ts

@@ -1,6 +1,6 @@
 /**
- * Connector manifest validation for `trove connector validate`
- * (see the connectors manifest reference).
+ * Source manifest validation for `trove source validate`
+ * (see the sources manifest reference).
  *
  * Two checks live here:
  *
@@ -8,7 +8,7 @@
  *    `id` pattern (`^[a-z0-9-]+$`), and well-formedness of `config`.
  * 2. **Credential-key lint** — the same spirit as the server-side
  *    `validateConfig` (`src/graphql/validate-config.ts`, invariant #6): a
- *    connector's `config` holds **user preferences only, never credentials**.
+ *    source's `config` holds **user preferences only, never credentials**.
  *    The cloud rejects writes whose config contains credential-shaped keys, so
  *    the SDK lints the manifest locally to catch the mistake before deploy. Auth
  *    material belongs in the (PROPOSED) `auth` block — surfaced from the macOS
@@ -20,10 +20,10 @@
  * @module
  */
 
-import type { ConnectorManifest, ManifestConfigField } from './types.js';
+import type { ManifestConfigField, SourceManifest } from './types.js';
 
 /**
- * Credential-shaped key patterns that may NOT appear in a connector's `config`
+ * Credential-shaped key patterns that may NOT appear in a source's `config`
  * (invariant #6). Mirrors the authoritative cloud deny-list in
  * `src/graphql/validate-config.ts`. Matched case-insensitively and
  * separator-insensitively as substrings, so `apiKey`, `api_key`, `access_token`,
@@ -109,13 +109,13 @@ function validateConfigBlock(config: Record<string, ManifestConfigField>, errors
     const unique = [...new Set(offending)];
     errors.push(
       `manifest.config must not contain credential-shaped key(s): ${unique.join(', ')}. ` +
-        'Connector credentials belong in the macOS Keychain (declared as `auth`), not in `config`.',
+        'Source credentials belong in the macOS Keychain (declared as `auth`), not in `config`.',
     );
   }
 }
 
 /**
- * The outcome of {@link validateConnectorManifest}.
+ * The outcome of {@link validateSourceManifest}.
  */
 export interface ManifestValidationResult {
   /** True when no errors were found. */
@@ -125,7 +125,7 @@ export interface ManifestValidationResult {
 }
 
 /**
- * Validate a connector `manifest.json` for `trove connector validate`.
+ * Validate a source `manifest.json` for `trove source validate`.
  *
  * Checks required fields and the `id`/`version` patterns, validates the `config`
  * descriptors, and runs the credential-key lint (rejecting credential-shaped
@@ -136,14 +136,14 @@ export interface ManifestValidationResult {
  * @param manifest - The parsed manifest object to validate.
  * @returns `{ valid, errors }` — `valid: true` with an empty `errors` array on success.
  */
-export function validateConnectorManifest(manifest: unknown): ManifestValidationResult {
+export function validateSourceManifest(manifest: unknown): ManifestValidationResult {
   const errors: string[] = [];
 
   if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) {
     return { valid: false, errors: ['manifest must be a JSON object'] };
   }
 
-  const m = manifest as Partial<ConnectorManifest>;
+  const m = manifest as Partial<SourceManifest>;
 
   requireString(m.id, 'id', errors);
   if (typeof m.id === 'string' && m.id.length > 0 && !ID_RE.test(m.id)) {