doc: type-tagged objects, update share doc

doc/api/share.md

@@ -11,6 +11,35 @@ 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.
 
+### Example
+
+```json
+{
+    "recipients": [
+        "user_that_gets_shared_to",
+        "another@example.com"
+    ],
+    "shares": [
+        {
+            "$": "app-share",
+            "name": "some-app-name"
+        },
+        {
+            "$": "app-share",
+            "uid": "app-SOME-APP-UID"
+        },
+        {
+            "$": "fs-share",
+            "path": "/some/file/or/directory"
+        },
+        {
+            "$": "fs-share",
+            "path": "SOME-FILE-UUID"
+        }
+    ]
+}
+```
+
 ### Parameters
 
 - **recipients** _- required_
@@ -20,44 +49,14 @@ different from calling `/grant-user-user` with a permission.
   - **notes:**
     - validation on `string`: email or username
     - requirement of at least one value
-- **things:** _- required_
+- **shares:** _- required_
   - **accepts:** `object | Array<object>`
-  - **structure:**
-    - > `path`, `uid`, `name` are mutually exclusive
-    - **type:** _- required_
-      - **accepts:** one of: `fsitem`, `app`
-    - **uid:**
-      - **accepts:**
-        - file or directory (path or UUID)
-        - app UUID,
-    - **path:** _alias for uid_
-    - **name:** name of app
-    - **access:**
-      - `"read"` or `"write"` for files (default: `"read"`)
-      - unspecified for apps
+    - object is [type-tagged](./type-tagged.md)
+    - type is either [file-share](./types/file-share.md)
+      or [app-share](./types/app-share.md)
   - **notes:**
     - requirement that file/directory or app exists
     - requirement of at least one entry
-  - **examples:**
-    - ```json
-      {
-        "type": "fsitem",
-        "path": "/some/path",
-        "access": "write"
-      }
-      ```
-    - ```json
-      [
-        { "type": "fsitem", "path": "/some/path" },
-        { "type": "fsitem", "path": "/another/path" }
-      ]
-      ```
-    - ```json
-      {
-        "type": "app",
-        "uid": "app-7978dd66-e5a8-43a0-80c8-1c7eca8cb00a"
-      }
-      ```
 - **dry_run:** _- optional_
   - **accepts:** `bool`
   - **description:**
@@ -83,13 +82,28 @@ await fetch("http://puter.localhost:4100/share", {
     "Authorization": `Bearer ${puter.authToken}`,
   },
   body: JSON.stringify({
-      // dry_run: true,
-      recipients: [
-          'user_that_gets_shared_to',
-      ],
-      paths: [
-          '/user_that_shares/file_that_gets_shared.txt',
-      ],
+    recipients: [
+        "user_that_gets_shared_to",
+        "another@example.com"
+    ],
+    shares: [
+        {
+            $: "app-share",
+            name: "some-app-name"
+        },
+        {
+            $: "app-share",
+            uid: "app-SOME-APP-UID"
+        },
+        {
+            $: "fs-share",
+            path: "/some/file/or/directory"
+        },
+        {
+            $: "fs-share",
+            path: "SOME-FILE-UUID"
+        }
+    ]
   }),
   method: "POST",
 });

doc/api/type-tagged.md

@@ -0,0 +1,78 @@
+# Type-Tagged Objects
+
+```js
+{
+    "$": "some-type",
+    "$version": "0.0.0",
+    
+    "some_property": "some value",
+}
+```
+
+## What's a Type-Tagged Object?
+
+Type-Tagged objects are a convention understood by Puter's backend
+to communicate meta information along with a JSON object.
+The key feature of Type-Tagged Objects is the type key: `"$"`.
+
+## Why Type-Tagged Objects?
+
+The primary reason: to have a consistent convention we can use
+anywhere.
+
+- Since other services rarely use `$` in their property names,
+  we can safely use this without introducing reserved words and
+  re-mapping property names.
+- Some places we use this convention might not need it, but
+  staying consistent means API end-users can
+  [do more with less code](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).
+
+## Specification
+
+- The `"$"` key indicates a type (or class) of object
+- Any key beginning with `$` is a **meta-key**
+- Other keys are not allowed to contain `$`
+- `"$version"` must follow [semver](https://semver.org/)
+
+## Alternative Representations
+
+Puter's API will always send results in the format described
+above, which is called the "Standard Representation"
+
+Any endpoint which accepts a Type-Tagged Object will also
+accept these alternative representations:
+
+### Structured Representation
+
+Depending on the architecture of your client, this format
+may be more convenient to work with:
+```json
+{
+    "$": "$meta-body",
+    "type": "some-type",
+    "meta": { "version": "0.0.0" },
+    "body": { "some_property": "some value" }
+}
+```
+
+### Array Representation
+
+In the array representation, meta values go at the end.
+```json
+["some-type",
+    { "some_property": "some value" },
+    { "version": "0.0.0" }
+]
+```
+
+If the second element of the list is not an object, it
+will implicitly be placed in a property called value.
+The following are equivalent:
+
+```json
+["some-type", "hello"]
+```
+
+```json
+["some-type", { "value": "hello" }]
+```

doc/api/types/app-share.md

@@ -0,0 +1,26 @@
+# `{"$": "app-share"}` - File Share
+
+## Structure
+- **name:** name of the app
+- **uid:** name of the app
+
+## Notes
+- One of `name` or `uid` **must** be specified
+
+## Examples
+
+Share app by name
+```json
+{
+    "$": "app-share",
+    "name": "some-app-name"
+}
+```
+
+Share app by uid
+```json
+{
+    "$": "app-share",
+    "uid": "app-0a7337f7-0f8a-49ca-b71a-38d39304fe04"
+}
+```

doc/api/types/file-share.md

@@ -0,0 +1,32 @@
+# `{"$": "file-share"}` - File Share
+
+## Structure
+- **path:** file or directory's path or uuid
+- **access:** one of: `"read"`, `"write"` (default: `"read"`)
+
+## Examples
+
+Share with read access
+```json
+{
+    "$": "file-share",
+    "path": "/some/path"
+}
+```
+
+Share with write access
+```json
+{
+    "$": "file-share",
+    "path": "/some/path",
+    "access": "write"
+}
+```
+
+Using a UUID
+```json
+{
+    "$": "file-share",
+    "path": "b912c381-0c0b-466c-95a6-f9a4fc680a7d"
+}
+```