@octaviaflow/connect

Tell your Octaviaflow knowledge base which pages of your site changed, from any framework, right after a deploy. Also generates llms.txt from a static build. Node ≥ 20, zero runtime dependencies.

Only URLs leave your site. The platform reads the pages itself and re-indexes a page only when its text actually changed — so running this on every deploy costs nothing when nothing changed.

Setup

1. In Octaviaflow, add your site to a knowledge base (Add documents → From the web → Whole website / Sitemap / llms.txt). Copy the source token and the webhook URL from the dialog.
2. Put them in your CI as OCTAVIAFLOW_SOURCE_TOKEN and OCTAVIAFLOW_WEBHOOK_URL.

Sync after a deploy

# from a sitemap (any host, any framework)
npx @octaviaflow/connect sync --sitemap https://example.com/sitemap.xml

# from a static build directory (Next.js export, Astro, Vite, Hugo, Docusaurus…)
npx @octaviaflow/connect sync --dir ./out --base-url https://example.com

# see what would be sent
npx @octaviaflow/connect sync --dir ./out --base-url https://example.com --dry-run

The last run is remembered in .octaviaflow/connect-state.json (commit it, or cache it in CI). Pages whose text hash — or sitemap lastmod — changed are reported as upsert; pages that disappeared as delete. --full reports every page. Exit code 3 means the token was refused (rotate it in Octaviaflow and update the secret).

GitHub Actions example:

- run: npm run build
- run: npx @octaviaflow/connect sync --dir ./out --base-url https://example.com
  env:
    OCTAVIAFLOW_SOURCE_TOKEN: ${{ secrets.OCTAVIAFLOW_SOURCE_TOKEN }}
    OCTAVIAFLOW_WEBHOOK_URL: ${{ vars.OCTAVIAFLOW_WEBHOOK_URL }}

Generate llms.txt

npx @octaviaflow/connect llms --dir ./out --base-url https://example.com --out ./out/llms.txt

Title from the home page's <title> (or --title), one line per page with its title and first paragraph.

As a library

import { notifyChanges } from '@octaviaflow/connect';

await notifyChanges({
  webhookUrl: process.env.OCTAVIAFLOW_WEBHOOK_URL!,
  token: process.env.OCTAVIAFLOW_SOURCE_TOKEN!,
  changes: [{ url: 'https://example.com/blog/new-post', op: 'upsert' }],
  source: { kind: 'sanity-webhook', version: '1.0.0' },
});

notifyChanges signs the body exactly as the platform verifies it (Authorization: Bearer <token>, X-Octaviaflow-Signature: t=<unix>,v1=<hmac_sha256(token, t + "." + body)>), sends at most 500 changes per call, and throws a ConnectError with the platform's reason on a refusal.

Development

bun install
bun test
bun run typecheck
bun run build      # dist/index.js, dist/cli.js, dist/index.d.ts