Skip to content
Proof of ThoughtBuild

Share documents

View .md

Your app owns the sharing screen: who to invite, how invitations are sent, and what a shared link looks like. Proof owns the result: who may open each document and what they may do in it. By the end of this guide, your Share dialog writes members and link access to Proof, and anyone who opens a shared link gets the right role in the editor.

Proof checks roles on every session and every agent call, so what you write here takes effect at once, in open editors too.

Roles

Section titled “Roles”
Role In the editor, can
owner Everything an editor can, and seal the document. A document has one or more owners.
editor Write, accept and reject suggestions, and comment.
suggester Suggest changes and comment. Their suggestions wait for an editor.
viewer Read.

The first owner is whoever you name when you create the document. Who may share, change link access or delete is your app’s rule, enforced in your routes, since those actions go through your server. See Documents and access for the full rules.

Add and remove members

Section titled “Add and remove members”

When someone in your Share dialog invites a person, add them as a member with a role, by their Proof id. proofUserId is the helper from Embed the editor: it creates the Proof user the first time and returns the stored id after that.

share.ts
app.post("/notes/:id/members", requireSignIn, async (req, res) => {
  const { userId, role } = req.body; // from your Share dialog
  const invitee = await db.users.find(userId);


  await proof.members.put(req.params.id, await proofUserId(invitee), { role });


  await sendInviteEmail(invitee, req.params.id); // yours to send
  res.sendStatus(204);
});

Proof doesn’t check who is allowed to share: your route should. A common rule is the one Proof of Thought uses, where editors and owners may invite, and nobody may give a role above their own. Look up the caller’s role with GET /v1/documents/{id}/members if you don’t keep your own copy.

To change someone’s role, PUT it again. To remove them:

await proof.members.delete("doc_8Hq2Lm4R", "usr_9Tb3Wc1X");

Removing a member ends their access straight away. If Grace has the document open, Grace’s editor closes it and fires an error event with the code no_access. A change of role that changes how they write, such as editor to suggester, reloads their editor with the new role.

detail is the second line Proof shows under a name when someone types @ to mention a person, here the email address. Leave it out if your app doesn’t show emails to other people.

Section titled “Share by link”

Link access lets anyone who has the link open the document, with a role you choose, without being added as a member. It’s off (restricted) until the owner turns it on.

  1. Set the link’s role. When the owner picks “Anyone with the link can suggest” in your dialog:

    await proof.documents.update("doc_8Hq2Lm4R", { link_access: "suggest" });

    The values are restricted, view, suggest and edit.

  2. Give the link a page in your app. The link is your own URL, such as https://acme.com/n/doc_8Hq2Lm4R. Proof never hands out document links of its own.

  3. Start link sessions. When someone who isn’t a member opens that page, start their session with via: "link":

    const session = await proof.sessions.create({
      user: await proofUserId(visitor),
      document: "doc_8Hq2Lm4R",
      via: "link",
    });
    // session.role is "suggester" here: the link's role, or their member role if that's higher.

    Proof refuses it with no_access when link access is restricted. Visitors still need to be users: if your app lets people in without signing up, see Anonymous users.

Opening a document by link doesn’t make someone a member, so it doesn’t appear in their document list. If your app keeps a list of documents people have opened by link, keep it yourself, or add them as members when they first write.

Turning link access back to restricted ends every link session at once.

Owners

Section titled “Owners”

Give someone the owner role to make them an owner too. To hand a document over, make the new person an owner, then lower the old owner’s role or remove them. A document always keeps an owner: lowering or removing the last one is refused with 409 last_owner.

await proof.members.put("doc_8Hq2Lm4R", "usr_9Tb3Wc1X", { role: "owner" });
await proof.members.put("doc_8Hq2Lm4R", "usr_5Kq2Lm8R", { role: "editor" });

Seals already made keep the name of whoever sealed them.

What agents get

Section titled “What agents get”

An agent acts for one person, and can never do more than that person can. Its role in a document is the lower of the role its person gave it and the person’s own current role. So your sharing changes reach agents with no extra work:

  • Remove Grace from a document, and Grace’s agents lose it at the same moment.
  • Make Grace a viewer, and Grace’s agents can only read, even if Grace gave them editing.
  • Turn on link access, and agents of people who have the link may reach the document too, by its id, with at most the link’s role: an agent with access: "all" reaches any document its person can open. Its list_documents lists only documents its person is a member of.

Agents can never be owners. See Connect agents for how people choose what each agent reaches.

Next

Section titled “Next”