diff --git a/src/docs/src/Events/subjects.md b/src/docs/src/Events/subjects.md index aab0311d7..0376fb9ae 100644 --- a/src/docs/src/Events/subjects.md +++ b/src/docs/src/Events/subjects.md @@ -102,6 +102,8 @@ Entries the other app wrote with `disableSharing` are never delivered. Marking a ## Sharing key-value data with another user +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ `kv:` always means your own data. When another user shares part of theirs with you using [`puter.kv.share()`](/KV/share/), you watch it through the share's **handle**, which goes where an app id would go. For a walkthrough, see [Send Live Updates to Other Users](/recipes/send-live-updates-to-other-users/). ```js diff --git a/src/docs/src/KV.md b/src/docs/src/KV.md index 7ffc6ef82..7feec99c7 100644 --- a/src/docs/src/KV.md +++ b/src/docs/src/KV.md @@ -232,6 +232,8 @@ These Key-Value Store features are supported out of the box when using Puter.js: ## Sharing with other users +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ A user can share the keys under a prefix with another Puter user. The user who shares is the share's owner, and the user it's shared with is its holder. The keys stay in the owner's store. Pick the tool by what you want to do: diff --git a/src/docs/src/KV/add.md b/src/docs/src/KV/add.md index c48bfed5f..ac88457d7 100644 --- a/src/docs/src/KV/add.md +++ b/src/docs/src/KV/add.md @@ -38,6 +38,8 @@ A plain object is read as a path map, never appended as an element: to append an #### `optConfig` (Object) (optional) +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ The last argument. It takes these properties: - `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). diff --git a/src/docs/src/KV/decr.md b/src/docs/src/KV/decr.md index 56e94034a..7bd5cd8c2 100755 --- a/src/docs/src/KV/decr.md +++ b/src/docs/src/KV/decr.md @@ -36,6 +36,8 @@ Paths support dot notation, array indexes at any level (`[0]`, `items[0]`, or `s #### `optConfig` (Object) (optional) +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ The last argument. It takes these properties: - `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). diff --git a/src/docs/src/KV/del.md b/src/docs/src/KV/del.md index 09c767ba1..c1bd9ba29 100755 --- a/src/docs/src/KV/del.md +++ b/src/docs/src/KV/del.md @@ -18,6 +18,8 @@ A string containing the name of the key you want to remove. #### `optConfig` (Object) (optional) +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ The last argument. It takes these properties: - `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). diff --git a/src/docs/src/KV/expire.md b/src/docs/src/KV/expire.md index c2ece76f4..204161d37 100644 --- a/src/docs/src/KV/expire.md +++ b/src/docs/src/KV/expire.md @@ -25,6 +25,8 @@ The number of seconds until the key is removed from the key-value store. `0` or #### `optConfig` (Object) (optional) +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ The last argument. It takes these properties: - `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). diff --git a/src/docs/src/KV/expireAt.md b/src/docs/src/KV/expireAt.md index 1b0f97b8b..6b2d0dabd 100644 --- a/src/docs/src/KV/expireAt.md +++ b/src/docs/src/KV/expireAt.md @@ -25,6 +25,8 @@ The Unix timestamp (in seconds) at which the key will be removed from the key-va #### `optConfig` (Object) (optional) +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ The last argument. It takes these properties: - `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). diff --git a/src/docs/src/KV/flush.md b/src/docs/src/KV/flush.md index 1968dce8e..5a40421c6 100755 --- a/src/docs/src/KV/flush.md +++ b/src/docs/src/KV/flush.md @@ -17,6 +17,8 @@ None ## Return value A `Promise` that will resolve to `true` when the key-value store has been flushed (emptied), or reject with an error on failure. +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ Flushing works only on your own store. Passing the `handle` of data another user shared with you is rejected with `kv_handle_option_invalid`. To clear a shared prefix, delete its keys with [`puter.kv.del()`](/KV/del/). ## Examples diff --git a/src/docs/src/KV/get.md b/src/docs/src/KV/get.md index 836cee8ef..380aaa2f1 100755 --- a/src/docs/src/KV/get.md +++ b/src/docs/src/KV/get.md @@ -18,6 +18,8 @@ A string containing the name of the key you want to retrieve the value of. #### `optConfig` (Object) (optional) +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ The last argument. It takes these properties: - `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `read` or `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). diff --git a/src/docs/src/KV/incr.md b/src/docs/src/KV/incr.md index 21cc6dedd..f1f344a18 100755 --- a/src/docs/src/KV/incr.md +++ b/src/docs/src/KV/incr.md @@ -36,6 +36,8 @@ Paths support dot notation, array indexes at any level (`[0]`, `items[0]`, or `s #### `optConfig` (Object) (optional) +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ The last argument. It takes these properties: - `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). diff --git a/src/docs/src/KV/list.md b/src/docs/src/KV/list.md index 692c9bdc9..cfd983777 100755 --- a/src/docs/src/KV/list.md +++ b/src/docs/src/KV/list.md @@ -35,6 +35,8 @@ If set to `true`, the returned array will contain objects with both `key` and `v #### `optConfig` (Object) (optional) +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ The last argument of the positional forms. It takes these properties: - `handle` (String): List data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The share needs `read` or `write` access. The `pattern` is relative to the shared prefix and can be at most 768 bytes, and the returned keys are relative to the prefix too. The results and `total` leave out private entries. Every page of a full listing or a stream is fetched through the handle. See [Sharing with other users](/KV/#sharing-with-other-users). diff --git a/src/docs/src/KV/listShared.md b/src/docs/src/KV/listShared.md index 31d8f4b82..37161b954 100644 --- a/src/docs/src/KV/listShared.md +++ b/src/docs/src/KV/listShared.md @@ -4,6 +4,8 @@ description: List the key-value data other users have shared with you. platforms: [websites, apps, nodejs, workers] --- +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ Lists the live shares other users made with you, a page at a time. Each share comes with the `handle` you pass to the other [`puter.kv`](/KV/) methods to use it. A share tells you its level, its app, and the owner's label. It never says 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 a `watch` share only has its label. diff --git a/src/docs/src/KV/listSharedByMe.md b/src/docs/src/KV/listSharedByMe.md index 30ceed32f..ca9b9fa57 100644 --- a/src/docs/src/KV/listSharedByMe.md +++ b/src/docs/src/KV/listSharedByMe.md @@ -4,6 +4,8 @@ description: List the key-value shares you made with other users, including ones platforms: [websites, apps, nodejs, workers] --- +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ Lists the shares you made with [`puter.kv.share()`](/KV/share/), a page at a time. Shares that stopped stay in the listing with `revokedAt` and `revokedBy` set, as a record of who had access and when it ended. In an app, the listing has only the shares of that app's data. Outside an app, it has every share you made. diff --git a/src/docs/src/KV/remove.md b/src/docs/src/KV/remove.md index 6bfcea407..729bb623c 100644 --- a/src/docs/src/KV/remove.md +++ b/src/docs/src/KV/remove.md @@ -27,6 +27,8 @@ Paths support dot notation, array indexes at any level (`[0]`, `items[0]`, or `s #### `optConfig` (Object) (optional) +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ The last argument. It takes these properties: - `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). diff --git a/src/docs/src/KV/set.md b/src/docs/src/KV/set.md index eacbc9bb4..66a893436 100755 --- a/src/docs/src/KV/set.md +++ b/src/docs/src/KV/set.md @@ -56,6 +56,8 @@ The batch form rejects it with `invalid_request`. #### `handle` (String) (optional) +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ Pass inside the trailing options object, as in `set(key, value, { handle })`, to write into data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). The batch form takes it too. With `handle`, a key can be at most 768 bytes. #### `items` (Array) (batch only) diff --git a/src/docs/src/KV/share.md b/src/docs/src/KV/share.md index b8dc76e23..158f5dcd6 100644 --- a/src/docs/src/KV/share.md +++ b/src/docs/src/KV/share.md @@ -4,6 +4,8 @@ description: Share the keys under a prefix with another Puter user, so they can platforms: [websites, apps, nodejs, workers] --- +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ Shares the keys under a prefix with another Puter user. The other user becomes the share's holder, and you stay its owner. The keys stay in your store, and the holder reaches them through the share. Each share has a `handle`. The holder finds it with [`puter.kv.listShared()`](/KV/listShared/) and passes it as `handle` to the other [`puter.kv`](/KV/) methods. [Sharing with other users](/KV/#sharing-with-other-users) shows how a holder uses a share. diff --git a/src/docs/src/KV/unshare.md b/src/docs/src/KV/unshare.md index f2cfed76f..dca0fbd16 100644 --- a/src/docs/src/KV/unshare.md +++ b/src/docs/src/KV/unshare.md @@ -4,6 +4,8 @@ description: Stop sharing key-value data with another user, or remove your own a platforms: [websites, apps, nodejs, workers] --- +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ Stops a share made with [`puter.kv.share()`](/KV/share/). Either side can call it: - **The owner** revokes the share. The holder loses access, and any narrower share you made with the same holder inside the same prefix stops too. diff --git a/src/docs/src/KV/update.md b/src/docs/src/KV/update.md index c57d0dde7..4de14c61a 100644 --- a/src/docs/src/KV/update.md +++ b/src/docs/src/KV/update.md @@ -35,6 +35,8 @@ Paths support dot notation, array indexes at any level (`[0]`, `items[0]`, or `s #### `optConfig` (Object) (optional) +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ The last argument. It takes these properties: - `handle` (String): Work on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix. The share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). diff --git a/src/docs/src/Perms/request.md b/src/docs/src/Perms/request.md index 48904f360..6e5e717a0 100644 --- a/src/docs/src/Perms/request.md +++ b/src/docs/src/Perms/request.md @@ -40,6 +40,8 @@ What the request is about. The resource decides which details are accepted and w | `'backgroundEvents'` | `Resource.BACKGROUND_EVENTS` | None | `true` if granted | | `'kvShare'` | `Resource.KV_SHARE` | `{ prefix, access }` | `true` if granted | +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ #### `details` (object) (optional) The fields the resource takes: diff --git a/src/docs/src/rate-limits-and-quotas.md b/src/docs/src/rate-limits-and-quotas.md index bce39ab47..34cd33450 100644 --- a/src/docs/src/rate-limits-and-quotas.md +++ b/src/docs/src/rate-limits-and-quotas.md @@ -186,6 +186,8 @@ Before the provider runs, the balance must cover every page the call can be bill ### Key-value store +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ | Limit | Paid | Free | Anonymous | | ------------------------------- | ---- | ---- | --------- | | `get` / `set` / etc. per 10 s | 400 | 400 | 200 | @@ -422,6 +424,8 @@ See [Events](/Events/) for an overview, [`onLocal()`](/Events/subjects/#gaps) fo #### What an account can hold +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ | Limit | Scope | Paid | Free | Anonymous | | ------------------------------------ | ------------------ | ---- | ---- | --------- | | Persistent subscriptions | Per user, all apps | 500 | 100 | 0 | diff --git a/src/docs/src/recipes/build-a-group-chat.md b/src/docs/src/recipes/build-a-group-chat.md index 9a8106c99..9f0dd1b1f 100644 --- a/src/docs/src/recipes/build-a-group-chat.md +++ b/src/docs/src/recipes/build-a-group-chat.md @@ -5,6 +5,8 @@ tags: [kv, events, perms] order: 22 --- +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ A group chat usually needs a server that stores the messages and sends each new one to everyone in the room. With [`puter.kv.share()`](/KV/share/), the room can live in the Puter account of the user who creates it instead. Each member gets diff --git a/src/docs/src/recipes/let-someone-view-your-data.md b/src/docs/src/recipes/let-someone-view-your-data.md index 24faf4779..a7a836065 100644 --- a/src/docs/src/recipes/let-someone-view-your-data.md +++ b/src/docs/src/recipes/let-someone-view-your-data.md @@ -5,6 +5,8 @@ tags: [kv, perms] order: 18 --- +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ A fitness app keeps each user's workouts in their own Puter account. A user who trains with a coach wants the coach to see the log, but not change it. With [`puter.kv.share()`](/KV/share/) and read access, the coach can read and list diff --git a/src/docs/src/recipes/manage-who-has-access-to-shared-data.md b/src/docs/src/recipes/manage-who-has-access-to-shared-data.md index fcf4498f8..a7eaf1b8d 100644 --- a/src/docs/src/recipes/manage-who-has-access-to-shared-data.md +++ b/src/docs/src/recipes/manage-who-has-access-to-shared-data.md @@ -5,6 +5,8 @@ tags: [kv, perms] order: 21 --- +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ Once users share data in your app, they need a way to see who has it and to take it back. This recipe builds two screens, a "People with access" panel for the data a user shared and a "Shared with me" list for the data other people diff --git a/src/docs/src/recipes/send-live-updates-to-other-users.md b/src/docs/src/recipes/send-live-updates-to-other-users.md index accf476ae..559afda62 100644 --- a/src/docs/src/recipes/send-live-updates-to-other-users.md +++ b/src/docs/src/recipes/send-live-updates-to-other-users.md @@ -5,6 +5,8 @@ tags: [kv, events] order: 19 --- +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ A scoreboard app keeps the score of a game in the scorekeeper's Puter account. Fans want to see each change as it happens. With a watch share, another Puter user gets an [event](/Events/) each time a key under a prefix changes, with the diff --git a/src/docs/src/recipes/share-a-list-with-someone.md b/src/docs/src/recipes/share-a-list-with-someone.md index de8017220..4ce6ff2f9 100644 --- a/src/docs/src/recipes/share-a-list-with-someone.md +++ b/src/docs/src/recipes/share-a-list-with-someone.md @@ -5,6 +5,8 @@ tags: [kv, perms] order: 17 --- +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ [`puter.kv`](/KV/) keeps each user's data in their own Puter account, where only they can reach it. A shared grocery list or to-do list needs two people working on the same data. With [`puter.kv.share()`](/KV/share/), a user can give another diff --git a/src/docs/src/recipes/share-data-from-your-backend.md b/src/docs/src/recipes/share-data-from-your-backend.md index 259ed042b..5ac602d24 100644 --- a/src/docs/src/recipes/share-data-from-your-backend.md +++ b/src/docs/src/recipes/share-data-from-your-backend.md @@ -5,6 +5,8 @@ tags: [kv, perms, workers] order: 23 --- +
KV sharing is in beta. Method shapes, limits, and behavior may change between releases.
+ Some apps share data without the user clicking a share button. A team chat app can share each new room with the whole team as soon as it's created, or a backend can add a member to a room when your own rules say so. In both cases your app calls