news.feed

Describes a subscription to real-time news stories, edits, and deletions. Nothing connects until the request is executed with velo.watch().

Imports

import { Velo } from 'velo-sdk';

Examples

Listeners can be passed as arguments, one per event type:

import { Velo, news } from 'velo-sdk';
 
const velo = new Velo({ apiKey: process.env.VELO_API_KEY! });
 
const watcher = await velo.watch(news.feed(), {
  on: {
    story: (story) => console.log('New:', story.headline),
    edit: (story) => console.log('Edited:', story.headline),
    delete: ({ id }) => console.log('Deleted:', id),
    error: (error) => console.error('News connection failed', error),
  },
  onListenerError: (error) => {
    console.error('News listener failed', error);
  },
});
 
// Later:
watcher.close();

Or as a single listener receiving every event, discriminated by type:

const watcher = await velo.watch(news.feed(), {
  on: (event) => {
    switch (event.type) {
      case 'story':
        console.log('New:', event.event.headline);
        break;
      case 'edit':
        console.log('Edited:', event.event.headline);
        break;
      case 'delete':
        console.log('Deleted:', event.event.id);
        break;
      case 'error':
        console.error('News connection failed', event.event);
        break;
      case 'close':
        console.log('Closed:', event.event.reason);
        break;
    }
  },
});

.on() and .off() remain available for adding and removing listeners later.

Definition

function feed(): NewsFeedBuilder;

Parameters

None. The live feed delivers every published story.

Return Type

Type: NewsFeedBuilder

Returns an immutable subscription builder. Pass it to velo.watch() to open a subscription.

Watching the feed

Pass the builder to velo.watch() to execute the subscription. The socket opens immediately, and the returned promise resolves to a NewsWatcher once the subscription is live. By default, failed initial connections are retried and the promise remains pending; disabling reconnection or setting a finite retry budget allows it to reject.

Property	Type	Description
`on`	listeners	Either a map of per-event listeners or one function receiving every event, tagged with `type`.
`reconnect`	`boolean \| ResumeOptions`	Reconnects automatically after an unexpected drop, with jittered backoff. On by default. Pass `false` to opt out, or `{ baseDelayMs, maxDelayMs, retries }` to tune it, and omitting `retries` keeps trying.
`signal`	`AbortSignal`	Permanently closes the watcher when aborted.
`heartbeatTimeout`	`number`	Maximum time between heartbeat messages, in milliseconds. Defaults to `300_000`.
`connectTimeout`	`number`	Maximum time for `.connect()` to open and subscribe, in milliseconds. Defaults to `30_000`.
`onListenerError`	`(error: unknown) => unknown`	Handles errors thrown or rejected by event listeners.

Both timeout values must be positive safe integers.

NewsWatcher

A reusable watcher with a read-only state property.

Method	Description
`.on(type, listener)`	Adds a listener and returns the watcher. Adding the same listener more than once has no additional effect.
`.off(type, listener)`	Removes a listener and returns the watcher.
`.connect()`	Reopens the subscription. Not needed for the first connection, which `velo.watch()` performs, nor after an unexpected drop, which reconnects on its own. Concurrent calls share one connection attempt.
`.disconnect()`	Intentionally disconnects while preserving the watcher and its listeners for reuse.
`.close()`	Permanently closes the watcher and clears its listeners. Calling it more than once is safe.

Events

Event	Payload	Description
`story`	`NewsStory`	A newly published story.
`edit`	`NewsStory`	An updated story.
`delete`	`NewsDelete`	An object containing the deleted story's numeric `id`.
`error`	`VeloError`	A failure after the watcher has opened, such as a malformed message or heartbeat timeout.
`close`	`NewsClose`	The WebSocket close `code`, `reason`, and `wasClean` status.

NewsStory has the same fields returned by .stories().

States

The watcher can be idle, connecting, open, disconnected, or closed. An unexpected connection loss moves it to disconnected, and the subscription reopens itself with jittered backoff until it is live again.

Intentional endings never reconnect: disconnect() leaves the watcher idle and reusable, close() and an aborted signal leave it closed.

Errors thrown or rejected by event listeners do not close the connection. They are passed to onListenerError, or reported with the runtime's default error reporting when that option is omitted.