@ontrove/sdk 0.1.0 → 0.3.1

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)) {

package/src/runtime.ts

@@ -1,27 +1,27 @@
 /**
- * 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
  */
 
 import type {
-  ConnectorContext,
-  ConnectorDocument,
-  ConnectorSyncResult,
   FetchLike,
-  TroveConnector,
+  SourceContext,
+  SourceDocument,
+  SourceSyncResult,
+  TroveSource,
   Watermark,
 } from './types.js';
 
@@ -29,16 +29,16 @@ import type {
 const CONTENT_TYPES: readonly string[] = ['text', 'transcript', 'highlight', 'bookmark'];
 
 /**
- * The options {@link runConnector} builds a `ctx` from. The CLI passes the
- * source's stored config and current cursor; tests inject `fetch`, `log`, and
- * `now` for determinism.
+ * The options {@link runSource} builds a `ctx` from. The CLI passes the
+ * source's stored config and the feed's current cursor; tests inject `fetch`,
+ * `log`, and `now` for determinism.
  *
- * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
+ * @typeParam C - The shape of the source's typed `ctx.config` preferences.
  */
 export interface RunOptions<C = Record<string, unknown>> {
   /** The source's preference values (no credentials). Defaults to `{}`. */
   config?: C;
-  /** The source's current watermark. Defaults to `{ type: 'none' }`. */
+  /** The feed's current watermark. Defaults to `{ type: 'none' }`. */
   cursor?: Watermark;
   /** The fetch implementation to expose as `ctx.fetch`. Defaults to global `fetch`. */
   fetchImpl?: FetchLike;
@@ -49,13 +49,13 @@ export interface RunOptions<C = Record<string, unknown>> {
 }
 
 /**
- * The outcome of {@link runConnector}: the validated, deduped documents, the
+ * The outcome of {@link runSource}: the validated, deduped documents, the
  * resolved cursor, and the captured log lines. Mirrors enough of what the cloud
- * ingest reports for `trove connector test` to print a useful summary.
+ * ingest reports for `trove source test` to print a useful summary.
  */
 export interface RunResult {
   /** The validated, deduped documents `sync` returned. */
-  documents: ConnectorDocument[];
+  documents: SourceDocument[];
   /** The cursor `sync` returned, or `{ type: 'none' }` if it returned none. */
   cursor: Watermark;
   /** Captured `ctx.log(...)` lines (when no custom `logSink` was supplied). */
@@ -73,7 +73,7 @@ export interface RunResult {
  * @param index - Its position in the returned array, for the message.
  * @throws {Error} If a required field is missing or malformed.
  */
-function validateDocument(doc: ConnectorDocument, index: number): void {
+function validateDocument(doc: SourceDocument, index: number): void {
   const where = `document[${String(index)}]`;
   if (doc === null || typeof doc !== 'object') {
     throw new Error(`${where} must be an object`);
@@ -97,14 +97,14 @@ function validateDocument(doc: ConnectorDocument, index: number): void {
 }
 
 /**
- * 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.
  * @returns A normalized `{ documents, cursor? }` result.
  * @throws {Error} If the value is neither an array nor a `{ documents }` object.
  */
-function normalizeResult(value: ConnectorSyncResult | ConnectorDocument[]): ConnectorSyncResult {
+function normalizeResult(value: SourceSyncResult | SourceDocument[]): SourceSyncResult {
   if (Array.isArray(value)) {
     return { documents: value };
   }
@@ -118,17 +118,17 @@ function normalizeResult(value: ConnectorSyncResult | ConnectorDocument[]): Conn
 
 /**
  * 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.
  */
-function dedup(documents: ConnectorDocument[]): {
-  unique: ConnectorDocument[];
+function dedup(documents: SourceDocument[]): {
+  unique: SourceDocument[];
   duplicatesSkipped: number;
 } {
   const seen = new Set<string>();
-  const unique: ConnectorDocument[] = [];
+  const unique: SourceDocument[] = [];
   let duplicatesSkipped = 0;
   for (const doc of documents) {
     if (seen.has(doc.id)) {
@@ -142,23 +142,23 @@ function dedup(documents: ConnectorDocument[]): {
 }
 
 /**
- * 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<C = Record<string, unknown>>(
-  connector: TroveConnector<C>,
+export async function runSource<C = Record<string, unknown>>(
+  source: TroveSource<C>,
   options: RunOptions<C> = {},
 ): Promise<RunResult> {
   const logs: unknown[][] = [];
@@ -166,7 +166,7 @@ export async function runConnector<C = Record<string, unknown>>(
   const fetchImpl: FetchLike = options.fetchImpl ?? ((url, init) => globalThis.fetch(url, init));
   const now = options.now ?? (() => new Date());
 
-  const ctx: ConnectorContext<C> = {
+  const ctx: SourceContext<C> = {
     config: options.config ?? ({} as C),
     cursor,
     fetch: fetchImpl,
@@ -180,7 +180,7 @@ export async function runConnector<C = Record<string, unknown>>(
     now,
   };
 
-  const raw = await connector.sync(ctx);
+  const raw = await source.sync(ctx);
   const result = normalizeResult(raw);
 
   result.documents.forEach(validateDocument);

package/src/types.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
  */
@@ -18,10 +20,10 @@
  * 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 |
@@ -37,15 +39,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.
    */
@@ -80,7 +82,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>;
@@ -89,20 +91,20 @@ 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 =
@@ -111,16 +113,16 @@ 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).
    */
@@ -128,20 +130,20 @@ export interface ConnectorSyncResult {
 }
 
 /**
- * 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;
@@ -174,16 +176,16 @@ export interface ConnectorContext<C = Record<string, unknown>> {
 }
 
 /**
- * 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());
@@ -191,19 +193,19 @@ 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. */
@@ -215,12 +217,12 @@ export interface ManifestConfigField {
 }
 
 /**
- * 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;
@@ -230,23 +232,23 @@ 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;
 }