connect.downloads

Start your own downloads and observe only them. Deliberately narrower than Chrome: there is no surveillance of the user's downloads — an extension sees its own and nothing else.

• Capability: downloads
• Namespace: connect.downloads

Walkthrough

Download a file and know when it's done.

1. Declare downloads:

   { "capabilities": ["downloads"] }

2. Start the download and keep its id:

   const { id } = await connect.downloads.download({ url, filename: 'report.pdf' });

3. Watch for completion with onChanged (you only hear about your downloads).

Methods

downloads.download(options)

Start a download.

How to use it

1. Pass a url (and optional filename — it's basename-sanitised).
2. await { id }; track completion via onChanged.

Signature — connect.downloads.download({ url, filename? })

Parameters

Returns — Promise<{ id }>. Saves silently into the OS downloads directory.

const { id } = await connect.downloads.download({
  url: 'https://example.com/report.pdf',
  filename: 'report.pdf',
});

Events

downloads.onChanged(cb)

Fires as your downloads progress to a terminal state.

How to use it

1. Subscribe once.
2. Match id to a download you started; on state: 'completed', use path.

Payload

connect.downloads.onChanged(({ id, state, path }) => {
  if (state === 'completed') console.log('saved', path);
});

Notes

• You only ever hear about downloads you started — never the user's or another extension's.
• The file lands in the OS downloads dir; filename is a basename, so you can't write outside it.