From 5a49074f957e6a80433937401c5bb65bf98845af Mon Sep 17 00:00:00 2001
From: KernelDeimos <eric.alex.dube@gmail.com>
Date: Thu, 20 Jun 2024 22:10:11 -0400
Subject: [PATCH] doc: sharelink endpoints

---
 doc/api/concepts/share-link.md |   9 +++
 doc/api/share.md               | 104 +++++++++++++++++++++++++++++++++
 2 files changed, 113 insertions(+)
 create mode 100644 doc/api/concepts/share-link.md

diff --git a/doc/api/concepts/share-link.md b/doc/api/concepts/share-link.md
new file mode 100644
index 00000000..8d8f0381
--- /dev/null
+++ b/doc/api/concepts/share-link.md
@@ -0,0 +1,9 @@
+# Share Links
+
+A **share link** is a link to Puter's origin which contains a token
+in the query string (the key is `share_token`; ex:
+`http://puter.localhost:4100?share_token=...`).
+
+This token can be used to apply permissions to the user of the
+current session **if and only if** this user's email is confirmed
+and matches the share link's associated email.
diff --git a/doc/api/share.md b/doc/api/share.md
index 99e99cb7..17d760c5 100644
--- a/doc/api/share.md
+++ b/doc/api/share.md
@@ -11,6 +11,9 @@ with one or more recipients. The recipients will receive
 some notification about the shared item, making this
 different from calling `/grant-user-user` with a permission.
 
+When users are **specified by email** they will receive
+a [share link](./concepts/share-link.md).
+
 ### Example
 
 ```json
@@ -182,3 +185,104 @@ await fetch("http://puter.localhost:4100/share", {
     "dry_run": true
 }
 ```
+
+## POST `/sharelink/check` (no auth)
+
+### Description
+
+The `/sharelink/check` endpoint verifies that a token provided
+by a share link is valid.
+
+### Example
+
+```javascript
+await fetch(`${config.api_origin}/sharelink/check`, {
+  "headers": {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${puter.authToken}`,
+  },
+  "body": JSON.stringify({
+      token: '...',
+  }),
+  "method": "POST",
+});
+```
+
+### Parameters
+
+- **token:** _- required_
+  - **accepts:** `string`
+    The token from the querystring parameter
+
+### Response
+
+A type-tagged object, either of type `api:share` or `api:error`
+
+### Success Response
+
+```json
+{
+    "$": "api:share",
+    "uid": "836671d4-ac5d-4bd3-bc0a-ec357e0d8f02",
+    "email": "asdf@example.com"
+}
+```
+
+### Error Response
+
+```json
+{
+    "$": "api:error",
+    "message":"Field `token` is required.",
+    "key":"token",
+    "code":"field_missing"
+}
+```
+
+## POST `/sharelink/apply` (no auth)
+
+### Description
+
+The `/sharelink/apply` endpoint applies a share to the current
+user **if and only if** that user's email is confirmed and matches
+the email associated with the share.
+
+### Example
+
+```javascript
+await fetch(`${config.api_origin}/sharelink/apply`, {
+  "headers": {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${puter.authToken}`,
+  },
+  "body": JSON.stringify({
+      uid: '836671d4-ac5d-4bd3-bc0a-ec357e0d8f02',
+  }),
+  "method": "POST",
+});
+```
+
+### Parameters
+
+- **uid:** _- required_
+  - **accepts:** `string`
+    The uid of an existing share, received using `/sharelink/check`
+
+### Response
+
+A type-tagged object, either of type `api:status-report` or `api:error`
+
+### Success Response
+
+```json
+{"$":"api:status-report","status":"success"}
+```
+
+### Error Response
+
+```json
+{
+    "message": "This share can not be applied to this user.",
+    "code": "can_not_apply_to_this_user"
+}
+```