@ontrove/sdk 0.1.0

package/src/manifest.ts

@@ -0,0 +1,173 @@
+/**
+ * Connector manifest validation for `trove connector validate`
+ * (see the connectors manifest reference).
+ *
+ * Two checks live here:
+ *
+ * 1. **Shape validation** — required fields (`id`, `name`, `version`), the
+ *    `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**.
+ *    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
+ *    Keychain — not in `config`.
+ *
+ * The deny-list below is kept deliberately identical in spirit to the
+ * authoritative cloud list so the two cannot meaningfully drift.
+ *
+ * @module
+ */
+
+import type { ConnectorManifest, ManifestConfigField } from './types.js';
+
+/**
+ * Credential-shaped key patterns that may NOT appear in a connector'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`,
+ * and `refreshToken` all match.
+ */
+const CREDENTIAL_KEY_PATTERNS: readonly string[] = [
+  'session',
+  'cookie',
+  'token',
+  'api_key',
+  'apikey',
+  'password',
+  'secret',
+  'auth',
+  'credential',
+  'bearer',
+  'access_key',
+  'private_key',
+];
+
+/** The `id` pattern: lowercase letters, digits, and hyphens. */
+const ID_RE = /^[a-z0-9-]+$/;
+
+/** A permissive semver check — `MAJOR.MINOR.PATCH` with optional pre-release/build. */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].+)?$/;
+
+/**
+ * Normalize a config key for credential-pattern matching: lowercase and strip
+ * `_`/`-` separators so `api_key`, `apiKey`, and `api-key` collapse to one form.
+ * Identical to the cloud's `normalizeKey`.
+ *
+ * @param key - The config key to normalize.
+ * @returns The normalized comparable form.
+ */
+function normalizeKey(key: string): string {
+  return key.toLowerCase().replaceAll('_', '').replaceAll('-', '');
+}
+
+/** Pre-normalized credential patterns, computed once. */
+const NORMALIZED_CREDENTIAL_PATTERNS: readonly string[] = CREDENTIAL_KEY_PATTERNS.map(normalizeKey);
+
+/**
+ * Whether a single config key looks like a credential and must be rejected.
+ * Mirrors the cloud's `isSensitiveConfigKey`.
+ *
+ * @param key - The config key to test.
+ * @returns True if the key matches a credential pattern.
+ */
+export function isCredentialConfigKey(key: string): boolean {
+  const normalized = normalizeKey(key);
+  return NORMALIZED_CREDENTIAL_PATTERNS.some((pattern) => normalized.includes(pattern));
+}
+
+/**
+ * Push an error if a required string field is missing or empty.
+ *
+ * @param value - The candidate field value.
+ * @param field - The field name, for the message.
+ * @param errors - The accumulator to append to.
+ */
+function requireString(value: unknown, field: string, errors: string[]): void {
+  if (typeof value !== 'string' || value.length === 0) {
+    errors.push(`manifest.${field} is required and must be a non-empty string`);
+  }
+}
+
+/**
+ * Validate the `config` block: each value must be an object descriptor, and no
+ * key may be credential-shaped.
+ *
+ * @param config - The manifest `config` object.
+ * @param errors - The accumulator to append to.
+ */
+function validateConfigBlock(config: Record<string, ManifestConfigField>, errors: string[]): void {
+  const offending: string[] = [];
+  for (const [key, descriptor] of Object.entries(config)) {
+    if (isCredentialConfigKey(key)) offending.push(key);
+    if (descriptor === null || typeof descriptor !== 'object' || Array.isArray(descriptor)) {
+      errors.push(`manifest.config.${key} must be a field descriptor object`);
+    }
+  }
+  if (offending.length > 0) {
+    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`.',
+    );
+  }
+}
+
+/**
+ * The outcome of {@link validateConnectorManifest}.
+ */
+export interface ManifestValidationResult {
+  /** True when no errors were found. */
+  valid: boolean;
+  /** Human-readable error messages; empty when `valid` is true. */
+  errors: string[];
+}
+
+/**
+ * Validate a connector `manifest.json` for `trove connector validate`.
+ *
+ * Checks required fields and the `id`/`version` patterns, validates the `config`
+ * descriptors, and runs the credential-key lint (rejecting credential-shaped
+ * `config` keys — same spirit as the server-side `validateConfig`). Returns a
+ * structured result rather than throwing, so the CLI can print all errors at
+ * once.
+ *
+ * @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 {
+  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>;
+
+  requireString(m.id, 'id', errors);
+  if (typeof m.id === 'string' && m.id.length > 0 && !ID_RE.test(m.id)) {
+    errors.push('manifest.id must match ^[a-z0-9-]+$ (lowercase letters, digits, hyphens)');
+  }
+
+  requireString(m.name, 'name', errors);
+
+  requireString(m.version, 'version', errors);
+  if (typeof m.version === 'string' && m.version.length > 0 && !SEMVER_RE.test(m.version)) {
+    errors.push('manifest.version must be a semver string (e.g. "1.0.0")');
+  }
+
+  if (m.config !== undefined) {
+    if (m.config === null || typeof m.config !== 'object' || Array.isArray(m.config)) {
+      errors.push('manifest.config must be an object');
+    } else {
+      validateConfigBlock(m.config, errors);
+    }
+  }
+
+  if (m.needs_browser !== undefined && typeof m.needs_browser !== 'boolean') {
+    errors.push('manifest.needs_browser must be a boolean');
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/runtime.ts

@@ -0,0 +1,195 @@
+/**
+ * The local-run harness — what makes `trove connector dev` / `trove connector test`
+ * work (connectors/sdk-reference; connectors/cursors-and-sources).
+ *
+ * {@link runConnector} builds a {@link ConnectorContext} 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
+ * 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
+ * sync end-to-end without the Mac app sync engine.
+ *
+ * @module
+ */
+
+import type {
+  ConnectorContext,
+  ConnectorDocument,
+  ConnectorSyncResult,
+  FetchLike,
+  TroveConnector,
+  Watermark,
+} from './types.js';
+
+/** Allowed `contentType` values (matches the GraphQL `ContentType` enum). */
+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.
+ *
+ * @typeParam C - The shape of the connector'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' }`. */
+  cursor?: Watermark;
+  /** The fetch implementation to expose as `ctx.fetch`. Defaults to global `fetch`. */
+  fetchImpl?: FetchLike;
+  /** A sink for `ctx.log(...)` calls. Defaults to collecting into the returned `logs`. */
+  logSink?: (args: unknown[]) => void;
+  /** The clock backing `ctx.now()`. Defaults to `() => new Date()`. */
+  now?: () => Date;
+}
+
+/**
+ * The outcome of {@link runConnector}: 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.
+ */
+export interface RunResult {
+  /** The validated, deduped documents `sync` returned. */
+  documents: ConnectorDocument[];
+  /** The cursor `sync` returned, or `{ type: 'none' }` if it returned none. */
+  cursor: Watermark;
+  /** Captured `ctx.log(...)` lines (when no custom `logSink` was supplied). */
+  logs: unknown[][];
+  /** Count of documents dropped as duplicates of an earlier `id`. */
+  duplicatesSkipped: number;
+}
+
+/**
+ * Validate one document's required fields, throwing a clear, indexed error on the
+ * first problem. Mirrors the wire contract: `id` is required (→ `externalId`),
+ * and at least one of `text`/`audioUrl` must be present.
+ *
+ * @param doc - The document to validate.
+ * @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 {
+  const where = `document[${String(index)}]`;
+  if (doc === null || typeof doc !== 'object') {
+    throw new Error(`${where} must be an object`);
+  }
+  if (typeof doc.id !== 'string' || doc.id.length === 0) {
+    throw new Error(`${where} is missing a non-empty string \`id\` (maps to externalId)`);
+  }
+  const hasText = typeof doc.text === 'string' && doc.text.length > 0;
+  const hasAudio = typeof doc.audioUrl === 'string' && doc.audioUrl.length > 0;
+  if (!hasText && !hasAudio) {
+    throw new Error(
+      `${where} (id "${doc.id}") must provide \`text\` or \`audioUrl\` — at least one is required`,
+    );
+  }
+  if (doc.contentType !== undefined && !CONTENT_TYPES.includes(doc.contentType)) {
+    throw new Error(
+      `${where} (id "${doc.id}") has invalid contentType "${String(doc.contentType)}"; ` +
+        `expected one of ${CONTENT_TYPES.join(', ')}`,
+    );
+  }
+}
+
+/**
+ * Normalize a `sync` return value to a {@link ConnectorSyncResult}, 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 {
+  if (Array.isArray(value)) {
+    return { documents: value };
+  }
+  if (value !== null && typeof value === 'object' && Array.isArray(value.documents)) {
+    return value.cursor === undefined
+      ? { documents: value.documents }
+      : { documents: value.documents, cursor: value.cursor };
+  }
+  throw new Error('sync must return an array of documents or an object with a `documents` array');
+}
+
+/**
+ * Deduplicate documents by `id`, keeping the first occurrence (matching the
+ * server's `(source, 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[];
+  duplicatesSkipped: number;
+} {
+  const seen = new Set<string>();
+  const unique: ConnectorDocument[] = [];
+  let duplicatesSkipped = 0;
+  for (const doc of documents) {
+    if (seen.has(doc.id)) {
+      duplicatesSkipped += 1;
+      continue;
+    }
+    seen.add(doc.id);
+    unique.push(doc);
+  }
+  return { unique, duplicatesSkipped };
+}
+
+/**
+ * Run a connector'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
+ * `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.
+ * @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>,
+  options: RunOptions<C> = {},
+): Promise<RunResult> {
+  const logs: unknown[][] = [];
+  const cursor: Watermark = options.cursor ?? { type: 'none' };
+  const fetchImpl: FetchLike = options.fetchImpl ?? ((url, init) => globalThis.fetch(url, init));
+  const now = options.now ?? (() => new Date());
+
+  const ctx: ConnectorContext<C> = {
+    config: options.config ?? ({} as C),
+    cursor,
+    fetch: fetchImpl,
+    log: (...args: unknown[]) => {
+      if (options.logSink !== undefined) {
+        options.logSink(args);
+      } else {
+        logs.push(args);
+      }
+    },
+    now,
+  };
+
+  const raw = await connector.sync(ctx);
+  const result = normalizeResult(raw);
+
+  result.documents.forEach(validateDocument);
+  const { unique, duplicatesSkipped } = dedup(result.documents);
+
+  return {
+    documents: unique,
+    cursor: result.cursor ?? { type: 'none' },
+    logs,
+    duplicatesSkipped,
+  };
+}

package/src/types.ts

@@ -0,0 +1,252 @@
+/**
+ * Public type surface for the `@ontrove/sdk` connector 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
+ * `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_.
+ *
+ * @module
+ */
+
+/**
+ * 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';
+
+/**
+ * A single document a connector returns from `sync`. The fields map **1:1** onto
+ * the GraphQL `IngestDocumentInput` the Mac app pushes via `ingestDocuments`:
+ *
+ * | SDK field     | `IngestDocumentInput` field |
+ * |---------------|-----------------------------|
+ * | `id`          | `externalId` (required)     |
+ * | `title`       | `title`                     |
+ * | `text`        | `text`                      |
+ * | `audioUrl`    | `audioUrl`                  |
+ * | `url`         | `url`                       |
+ * | `author`      | `author`                    |
+ * | `date`        | `date` (ISO 8601 DateTime)  |
+ * | `tags`        | `tags`                      |
+ * | `metadata`    | `metadata` (JSON)           |
+ * | `contentType` | `contentType` (ContentType) |
+ *
+ * Dedup is keyed on `(source, 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 {
+  /**
+   * The stable external identifier from the source system — the dedup key within
+   * the source. Maps to `IngestDocumentInput.externalId`. Use the native id (HN
+   * `objectID`, RSS `guid`, Notion page id), never a value that changes between
+   * runs.
+   */
+  id: string;
+  /** Document title. Maps to `IngestDocumentInput.title`. */
+  title?: string;
+  /**
+   * Full plain-text content. Maps to `IngestDocumentInput.text`. Strip HTML/markup
+   * for best search quality. Required unless `audioUrl` is set.
+   */
+  text?: string;
+  /**
+   * URL to an audio file. Maps to `IngestDocumentInput.audioUrl`. Trove downloads
+   * and transcribes it; the transcript becomes the document text and the document
+   * is indexed as `contentType: transcript`. Provide instead of (or alongside)
+   * `text`.
+   */
+  audioUrl?: string;
+  /** Canonical link back to the original. Maps to `IngestDocumentInput.url`. */
+  url?: string;
+  /**
+   * Content author. Maps to `IngestDocumentInput.author`. For podcasts, set this
+   * to the show name (Trove convention).
+   */
+  author?: string;
+  /**
+   * Original creation date as an ISO 8601 string (e.g. `"2026-06-14T09:00:00Z"`).
+   * Maps to the `DateTime` `IngestDocumentInput.date`. Used for recency ranking
+   * and the "published" display.
+   */
+  date?: string;
+  /** Array of string tags. Maps to `IngestDocumentInput.tags`. */
+  tags?: string[];
+  /**
+   * Arbitrary connector-specific JSON. Maps to `IngestDocumentInput.metadata`.
+   * **Never** put credentials or auth headers here.
+   */
+  metadata?: Record<string, unknown>;
+  /**
+   * One of `text`, `transcript`, `highlight`, `bookmark`. Maps to
+   * `IngestDocumentInput.contentType`. Defaults to `text` (transcribed audio
+   * becomes `transcript` automatically).
+   */
+  contentType?: ConnectorContentType;
+}
+
+/**
+ * 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).
+ *
+ * - `date` — the source 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
+ *   to the highest id seen (`max`), optionally tracking a recent id set.
+ * - `none` — re-fetch everything each run and rely purely on `(source, id)`
+ *   dedup. Always correct, just less efficient.
+ */
+export type Watermark =
+  | { readonly type: 'date'; readonly value: string }
+  | { readonly type: 'idSet'; readonly values: readonly string[]; readonly max?: string }
+  | { 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
+ * `{ documents }` with no cursor change.
+ */
+export interface ConnectorSyncResult {
+  /** The documents fetched this run, mapping 1:1 onto `IngestDocumentInput`. */
+  documents: ConnectorDocument[];
+  /**
+   * The watermark to advance the source 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}.
+ * 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
+ * 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
+ * of the shipped contract, and so are intentionally absent here.
+ */
+export interface ConnectorContext<C = Record<string, unknown>> {
+  /**
+   * The user's preference values, keyed by the field names declared in
+   * `manifest.json` `config`. **Preferences only — never credentials.** Feed
+   * URLs, usernames, section lists, and filters live here; auth material lives in
+   * the macOS Keychain, surfaced (PROPOSED) via `ctx.credentials`, never here.
+   */
+  readonly config: C;
+  /**
+   * The source'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.
+   */
+  fetch: FetchLike;
+  /**
+   * Structured log entry, surfaced in the Mac app's connector logs and the
+   * `createSyncRun` audit record. Useful for reporting counts and progress.
+   */
+  log(...args: unknown[]): void;
+  /**
+   * The current wall-clock time as a `Date`. Injected (rather than read from a
+   * global) so syncs are deterministic under test and the local-run harness.
+   */
+  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.
+ *
+ * @typeParam C - The shape of the connector's typed `ctx.config` preferences.
+ *
+ * @example
+ * ```ts
+ * import { defineConnector } from '@ontrove/sdk';
+ *
+ * export default defineConnector({
+ *   async sync(ctx) {
+ *     const res = await ctx.fetch(ctx.config.feedUrl as string);
+ *     return parse(await res.text());
+ *   },
+ * });
+ * ```
+ */
+export interface TroveConnector<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[]`
+   * 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[]>;
+}
+
+/**
+ * A single field descriptor inside a manifest `config` object — describes one
+ * preference input shown in the connector's setup wizard.
+ */
+export interface ManifestConfigField {
+  /** Display label in the setup UI. */
+  label?: string;
+  /** Input type — `text`, `text[]`, `url`, `url[]`, `path`, `number`, `boolean`. */
+  type?: string;
+  /** Optional example text shown in the input. */
+  placeholder?: string;
+}
+
+/**
+ * A connector `manifest.json` — declares what the connector is, how often it runs,
+ * and which preference fields the user fills in during setup
+ * (connectors/manifest reference).
+ */
+export interface ConnectorManifest {
+  /** Stable connector-type id; pattern `^[a-z0-9-]+$`. Required. */
+  id: string;
+  /** Human-readable display name. Required. */
+  name: string;
+  /** One-line directory description. */
+  description?: string;
+  /** A single emoji or an HTTPS URL to a square icon. */
+  icon?: string;
+  /** Semver version string. Required. */
+  version: string;
+  /** Who wrote the connector. */
+  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).
+   */
+  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`. */
+  needs_browser?: boolean;
+  /** What kind of source this is — `feed`, `account`, `files`, `api`. */
+  kind?: string;
+  /** How the connector reaches the source — `http`, `browser`, `fs`. */
+  transport?: string;
+  /** Default content type for documents this connector produces. */
+  document_semantics?: ConnectorContentType;
+}