puter.kv.listShared()

Copy page
Websites Puter Apps Node.js Workers

Lists the live shares other users made with you, a page at a time.

KV sharing is in beta. Method shapes, limits, and behavior may change between releases.

Each share comes with the handle you pass to the other puter.kv methods to use it.

A share tells you its level, its app, and the owner's label, but not who shared it or what the prefix is. To tell shares apart, read the label, or read a key the owner keeps for that, such as meta, through the handle. Reading needs read or write access, so for a watch share you have only the label.

In an app, the listing has only the shares of that app's data, and the handles work only in that app. Outside an app, it has every share made with you, and appUid narrows it to one app.

Syntax 

puter.kv.listShared()
puter.kv.listShared(options)

Parameters

options (Object) (optional)

An object with these properties:

Option Type Description
limit Number Shares per page. Defaults to 50. A value over 200 is lowered to 200.
cursor String The cursor from the previous page.
includeTotal Boolean Add total to the result. Defaults to false.
appUid String | null List only the shares of this app's data. Pass null for the store that belongs to no app. In an app, the only uid you can pass is the app's own.

Return value

A Promise that resolves to:

  • items (Array): The shares on this page, oldest first. Each has:
    • handle (String): Pass it as handle to use the share.
    • access (String): 'watch', 'read', or 'write'.
    • appUid (String | null): The app whose data it is, or null for the store that belongs to no app.
    • label (String | null): Plain text the owner set. Render it as text, with textContent, never as HTML.
    • notify (Boolean): Whether you and the owner can send each other notifications through the share with puter.notifications.notify().
    • createdAt (Number): When the share was made, in Unix seconds.
  • cursor (String): Pass it as cursor to get the next page. It's included only if there are more pages to load.
  • total (Number): The number of live shares across every page. Only included when includeTotal is true.

Shares that stopped aren't listed. An access token scoped to less than the account, such as the one in a getReadURL() URL, gets an empty page.

Errors

The promise rejects with { message, code }:

Code Meaning
events_kv_handle_outside_namespace The call came from an app and appUid names a different app, or null.
bad_request limit isn't a positive number, or appUid isn't an app uid.
too_many_requests Over the rate limit. See Rate Limits and Quotas.

Examples

Read every list shared with you 

const { items } = await puter.kv.listShared();
for (const { handle, access, label } of items) {
    // A watch share can't read keys, so it has only its label.
    const meta = access === 'watch' ? null : await puter.kv.get('meta', { handle });
    const row = document.createElement('li');
    row.textContent = label ?? meta?.title ?? 'Shared list';
    document.querySelector('#lists').append(row);
}

Page through every share 

let cursor;
const all = [];
do {
    const page = await puter.kv.listShared({ limit: 50, cursor });
    all.push(...page.items);
    cursor = page.cursor;
} while (cursor);

NEXT

listSharedByMe()

PREVIOUS

unshare()