@ontrove/sdk 0.1.0

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAEV,iBAAiB,EAEjB,SAAS,EACT,cAAc,EACd,SAAS,EACV,MAAM,YAAY,CAAC;AAKpB;;;;;;GAMG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACrD,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,sEAAsE;IACtE,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,qFAAqF;IACrF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wFAAwF;IACxF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,6EAA6E;IAC7E,MAAM,EAAE,SAAS,CAAC;IAClB,6EAA6E;IAC7E,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;IAClB,mEAAmE;IACnE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AA+ED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,UAAU,CAAC,CAAC,CAAM,GAC1B,OAAO,CAAC,SAAS,CAAC,CAgCpB"}

package/dist/runtime.js

@@ -0,0 +1,132 @@
+/**
+ * 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
+ */
+/** Allowed `contentType` values (matches the GraphQL `ContentType` enum). */
+const CONTENT_TYPES = ['text', 'transcript', 'highlight', 'bookmark'];
+/**
+ * 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, index) {
+    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) {
+    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) {
+    const seen = new Set();
+    const unique = [];
+    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(connector, options = {}) {
+    const logs = [];
+    const cursor = options.cursor ?? { type: 'none' };
+    const fetchImpl = options.fetchImpl ?? ((url, init) => globalThis.fetch(url, init));
+    const now = options.now ?? (() => new Date());
+    const ctx = {
+        config: options.config ?? {},
+        cursor,
+        fetch: fetchImpl,
+        log: (...args) => {
+            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/dist/types.d.ts

@@ -0,0 +1,250 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * 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
+ */
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "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.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Hollyburn Analytics Inc. <matt@hollyburnanalytics.com>",
+  "homepage": "https://ontrove.sh",
+  "bugs": {
+    "email": "matt@hollyburnanalytics.com"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "trove",
+    "connector",
+    "sdk",
+    "knowledge-base",
+    "ingestion",
+    "etl"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "src", "CHANGELOG.md", "LICENSE", "README.md"],
+  "sideEffects": false,
+  "scripts": {
+    "prepack": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "@vitest/coverage-v8": "^4.1.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1"
+  }
+}

package/src/define.ts

@@ -0,0 +1,70 @@
+/**
+ * `defineConnector` — the single entry point for authoring a Trove connector
+ * (connectors/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
+ * `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.
+ *
+ * @module
+ */
+
+import type {
+  ConnectorContext,
+  ConnectorDocument,
+  ConnectorSyncResult,
+  TroveConnector,
+} from './types.js';
+
+/**
+ * Validate and return a connector definition unchanged.
+ *
+ * Using `defineConnector(...)` (rather than a bare `satisfies TroveConnector`)
+ * gives an eager runtime check: the CLI calls this when loading a connector
+ * 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.
+ *
+ * @example
+ * ```ts
+ * export default defineConnector({
+ *   async sync(ctx) {
+ *     const res = await ctx.fetch(ctx.config.feedUrl as string);
+ *     return parseRss(await res.text());
+ *   },
+ * });
+ * ```
+ */
+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');
+  }
+  if (typeof (connector as { sync?: unknown }).sync !== 'function') {
+    throw new Error('defineConnector: connector must have a `sync(ctx)` function');
+  }
+  return connector;
+}
+
+/**
+ * A connector authored inline as a single `sync` function, for the common case
+ * where the connector has no other members. Equivalent to
+ * `defineConnector({ 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`.
+ */
+export function defineSync<C = Record<string, unknown>>(
+  sync: (ctx: ConnectorContext<C>) => Promise<ConnectorSyncResult | ConnectorDocument[]>,
+): TroveConnector<C> {
+  return defineConnector<C>({ sync });
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * `@ontrove/sdk` — the thin standard library for authoring **Trove connectors**.
+ * You write a `sync(ctx)` that fetches from a source 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`).
+ *
+ * @example
+ * ```ts
+ * import { defineConnector } from '@ontrove/sdk';
+ *
+ * export default defineConnector({
+ *   async sync(ctx) {
+ *     const res = await ctx.fetch('https://hn.algolia.com/api/v1/search?tags=front_page');
+ *     const { hits } = await res.json();
+ *     return hits.map((hit) => ({
+ *       id: hit.objectID,
+ *       title: hit.title,
+ *       text: hit.story_text ?? hit.title,
+ *       url: hit.url,
+ *       author: hit.author,
+ *       date: new Date(hit.created_at_i * 1000).toISOString(),
+ *       contentType: 'bookmark',
+ *     }));
+ *   },
+ * });
+ * ```
+ *
+ * @module
+ */
+
+export { defineConnector, defineSync } from './define.js';
+export {
+  isCredentialConfigKey,
+  type ManifestValidationResult,
+  validateConnectorManifest,
+} from './manifest.js';
+export {
+  type RunOptions,
+  type RunResult,
+  runConnector,
+} from './runtime.js';
+export type {
+  ConnectorContentType,
+  ConnectorContext,
+  ConnectorDocument,
+  ConnectorManifest,
+  ConnectorSyncResult,
+  FetchLike,
+  ManifestConfigField,
+  TroveConnector,
+  Watermark,
+} from './types.js';