puter.kv.listSharedByMe()

Copy page
Websites Puter Apps Node.js Workers

Lists the shares you made with puter.kv.share(), a page at a time.

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

A share that stopped stays in the listing for 30 days with revokedAt and revokedBy set, so you can see who had access and when it ended. After 30 days it's deleted.

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

Syntax 

puter.kv.listSharedByMe()
puter.kv.listSharedByMe(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.
state String Which shares to list. Pass 'live' for only shares that are still live, 'revoked' for only shares that stopped, or 'all' for both. Defaults to 'all'.
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): The share's id.
    • prefix (String): The shared prefix, ending with :.
    • access (String): 'watch', 'read', or 'write'.
    • appUid (String | null): The app whose data is shared, or null for the store that belongs to no app.
    • holder (String | null): The holder's username. When the holder deletes their account, their shares are deleted and leave this listing.
    • label (String | null): The label the holder is shown.
    • notify (Boolean): Whether you and the holder can send each other notifications through the share with puter.notifications.notify().
    • createdAt (Number): When the share was made, in Unix seconds.
    • revokedAt (Number | null): When the share stopped, in Unix seconds, or null while it's live.
    • revokedBy (String | null): Who stopped it. It's 'owner' when you revoked it, 'holder' when the holder removed their own access, and 'system' when the app whose data it was got deleted or you removed that app along with its data. It's null while the share is live, and can be null on an older share that stopped.
  • 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 shares across every page that match appUid and state. Only included when includeTotal is true.

Errors

The promise rejects with { message, code }:

Code Meaning
events_kv_handle_owner_only The call came from an access token with less access than the account.
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, appUid isn't an app uid, or state isn't 'live', 'revoked', or 'all'.
too_many_requests Over the rate limit. See Rate Limits and Quotas.

Examples

Show who has access, and who left 

const { items } = await puter.kv.listSharedByMe();
for (const share of items) {
    let state = share.access;
    if (share.revokedBy === 'holder') state = 'left';
    else if (share.revokedAt) state = 'removed';
    puter.print(`${share.holder}: ${share.prefix} (${state})<br>`);
}

Revoke everyone's access to one prefix 

let cursor;
do {
    const page = await puter.kv.listSharedByMe({ limit: 100, cursor, state: 'live' });
    for (const share of page.items) {
        if (share.prefix === 'list:42:') {
            await puter.kv.unshare(share.handle);
        }
    }
    cursor = page.cursor;
} while (cursor);

NEXT

MAX_KEY_SIZE

PREVIOUS

listShared()