# Sharing

The actions of the share group, with their input fields and their names on every transport.

21 actions: 20 on the command line, 21 as MCP tools, 21 as HTTP endpoints and 21 in the page.

## share.get

**Sharing.** The access record with its tokens hashed and the dead links of the last thirty days, plus the caller’s role, how it was reached and the capabilities it gives; a viewer receives the owner, the general access mode, their own grant and their capabilities only.

| Field | Type   | Required | Description |
| ----- | ------ | -------- | ----------- |
| `id`  | string | yes      |             |

* Command line: `turboslide share get <id>`
* MCP tool: `deck_get_share`
* HTTP: `POST /api/actions/share.get`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: no.

## share.setGeneralAccess

**General access.** Sets Restricted or Anyone with the link with its role; the link mode mints a token and answers its /s/ URL once.

| Field          | Type                                | Required | Description                                  |
| -------------- | ----------------------------------- | -------- | -------------------------------------------- |
| `id`           | string                              | yes      |                                              |
| `mode`         | "restricted" \| "link"              | yes      |                                              |
| `role`         | "viewer" \| "commenter" \| "editor" | no       | viewer unless set                            |
| `baseRevision` | integer                             | yes      | The access record’s revision the caller read |

* Command line: `turboslide share access <id> --mode <mode> --role <role>`
* MCP tool: `deck_set_general_access`
* HTTP: `POST /api/actions/share.setGeneralAccess`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.createLink

**Create link.** Mints a share link with a role, a label and an optional expiry and answers its /s/ URL once; several links with several roles may live at once.

| Field          | Type                                | Required | Description                                                      |
| -------------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `id`           | string                              | yes      |                                                                  |
| `role`         | "viewer" \| "commenter" \| "editor" | yes      |                                                                  |
| `label`        | string                              | no       |                                                                  |
| `expiresAt`    | string                              | no       | An ISO time, or 7d, 30d, 90d on the CLI; no expiry when absent   |
| `baseRevision` | integer                             | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share link <id> --role <role> --label <label> --expires <expiresAt>`
* MCP tool: `deck_create_share_link`
* HTTP: `POST /api/actions/share.createLink`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.revokeLink

**Revoke link.** Revokes one link; every session grant that names it dies on its next request.

| Field          | Type    | Required | Description                                                      |
| -------------- | ------- | -------- | ---------------------------------------------------------------- |
| `id`           | string  | yes      |                                                                  |
| `linkId`       | string  | yes      |                                                                  |
| `baseRevision` | integer | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share revoke-link <id> <linkId>`
* MCP tool: `deck_revoke_share_link`
* HTTP: `POST /api/actions/share.revokeLink`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.rotateLink

**Rotate link.** Mints a new token for a link and answers its URL once; the old token dies.

| Field          | Type    | Required | Description                                                      |
| -------------- | ------- | -------- | ---------------------------------------------------------------- |
| `id`           | string  | yes      |                                                                  |
| `linkId`       | string  | yes      |                                                                  |
| `baseRevision` | integer | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share rotate-link <id> <linkId>`
* MCP tool: `deck_rotate_share_link`
* HTTP: `POST /api/actions/share.rotateLink`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.stop

**Stop sharing.** Sets Restricted and revokes every link.

| Field          | Type    | Required | Description                                                      |
| -------------- | ------- | -------- | ---------------------------------------------------------------- |
| `id`           | string  | yes      |                                                                  |
| `baseRevision` | integer | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share stop <id>`
* MCP tool: `deck_stop_sharing`
* HTTP: `POST /api/actions/share.stop`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.invite

**Share with people.** Writes one grant per address with a role and an optional message and sends the invitations unless told not to; never says whether an account exists, and answers sent, queued or no-mail per address with the deck link for hand delivery.

| Field          | Type                                | Required | Description                                                      |
| -------------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `id`           | string                              | yes      |                                                                  |
| `emails`       | string\[]                           | yes      |                                                                  |
| `role`         | "viewer" \| "commenter" \| "editor" | yes      |                                                                  |
| `message`      | string                              | no       |                                                                  |
| `notify`       | boolean                             | no       | Send the invitation mail; on unless set                          |
| `baseRevision` | integer                             | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share invite <id> --email <emails> --role <role> --message <message> --no-notify`
* MCP tool: `deck_invite`
* HTTP: `POST /api/actions/share.invite`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.setRole

**Change role.** Changes a grant’s role; the owner’s row is refused.

| Field          | Type                                | Required | Description                                                      |
| -------------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `id`           | string                              | yes      |                                                                  |
| `who`          | object \| object                    | yes      |                                                                  |
| `role`         | "viewer" \| "commenter" \| "editor" | yes      |                                                                  |
| `baseRevision` | integer                             | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share role <id> --email <email> --role <role>`
* MCP tool: `deck_set_role`
* HTTP: `POST /api/actions/share.setRole`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.remove

**Remove access.** Removes a grant; the caller may remove their own at any role.

| Field          | Type             | Required | Description                                                      |
| -------------- | ---------------- | -------- | ---------------------------------------------------------------- |
| `id`           | string           | yes      |                                                                  |
| `who`          | object \| object | yes      |                                                                  |
| `baseRevision` | integer          | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share remove <id> --email <email>`
* MCP tool: `deck_remove_access`
* HTTP: `POST /api/actions/share.remove`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.setExpiry

**Access expiry.** Sets or clears a grant’s expiry, up to one year ahead.

| Field          | Type             | Required | Description                                                      |
| -------------- | ---------------- | -------- | ---------------------------------------------------------------- |
| `id`           | string           | yes      |                                                                  |
| `who`          | object \| object | yes      |                                                                  |
| `expiresAt`    | string \| null   | yes      | An ISO time within a year, or null to clear                      |
| `baseRevision` | integer          | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share expire <id> --email <email> --at <expiresAt>`
* MCP tool: `deck_set_access_expiry`
* HTTP: `POST /api/actions/share.setExpiry`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.settings

**Sharing settings.** The gear’s five switches: editors can share, viewers can download, viewers can see comments, show names to people with the link, allow embedded HTML blocks; owner only, with a re-authentication within 10 minutes on the window transport.

| Field                     | Type    | Required | Description                                                      |
| ------------------------- | ------- | -------- | ---------------------------------------------------------------- |
| `id`                      | string  | yes      |                                                                  |
| `editorsCanShare`         | boolean | no       |                                                                  |
| `viewersCanDownload`      | boolean | no       |                                                                  |
| `viewersCanSeeComments`   | boolean | no       |                                                                  |
| `showNamesToLinkVisitors` | boolean | no       |                                                                  |
| `allowHtmlBlocks`         | boolean | no       |                                                                  |
| `baseRevision`            | integer | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share settings <id> --editors-can-share <editorsCanShare> --viewers-can-download <viewersCanDownload> --viewers-can-see-comments <viewersCanSeeComments> --show-names-to-link-visitors <showNamesToLinkVisitors> --allow-html-blocks <allowHtmlBlocks>`
* MCP tool: `deck_share_settings`
* HTTP: `POST /api/actions/share.settings`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.requestAccess

**Request access.** Asks the owner for a role with an optional message; always answers the same sentence, so a caller learns nothing about whether the deck exists; rate limited per IP, and an anonymous caller must give an email.

| Field     | Type                                | Required | Description                    |
| --------- | ----------------------------------- | -------- | ------------------------------ |
| `id`      | string                              | yes      |                                |
| `role`    | "viewer" \| "commenter" \| "editor" | yes      |                                |
| `message` | string                              | no       |                                |
| `email`   | string                              | no       | Required for anonymous callers |

* Command line: No CLI command.
* MCP tool: `deck_request_access`
* HTTP: `POST /api/actions/share.requestAccess`
* Runs on: MCP, HTTP, page.
* Changes the presentation: yes.

## share.listRequests

**Access requests.** The pending requests with the requester’s label, email, role, message and time.

| Field | Type   | Required | Description |
| ----- | ------ | -------- | ----------- |
| `id`  | string | yes      |             |

* Command line: `turboslide share requests <id>`
* MCP tool: `deck_list_access_requests`
* HTTP: `POST /api/actions/share.listRequests`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: no.

## share.respond

**Respond to request.** Approves a request as a role or declines it with null; the requester is told when asked.

| Field          | Type                                        | Required | Description                                                      |
| -------------- | ------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `id`           | string                                      | yes      |                                                                  |
| `requestId`    | string                                      | yes      |                                                                  |
| `grant`        | "viewer" \| "commenter" \| "editor" \| null | yes      |                                                                  |
| `notify`       | boolean                                     | no       |                                                                  |
| `baseRevision` | integer                                     | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share respond <id> <requestId> --grant <grant> --notify`
* MCP tool: `deck_respond_access_request`
* HTTP: `POST /api/actions/share.respond`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.transferOwnership

**Transfer ownership.** Offers the deck to a signed in principal or an email, who accepts or declines; owner only, anonymous targets refused.

| Field          | Type             | Required | Description                                                      |
| -------------- | ---------------- | -------- | ---------------------------------------------------------------- |
| `id`           | string           | yes      |                                                                  |
| `to`           | object \| object | yes      |                                                                  |
| `baseRevision` | integer          | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share transfer <id> --email <email>`
* MCP tool: `deck_transfer_ownership`
* HTTP: `POST /api/actions/share.transferOwnership`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.acceptOwnership

**Accept ownership.** The pending owner takes the deck; the previous owner becomes an editor.

| Field          | Type    | Required | Description                                                      |
| -------------- | ------- | -------- | ---------------------------------------------------------------- |
| `id`           | string  | yes      |                                                                  |
| `baseRevision` | integer | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share accept-ownership <id>`
* MCP tool: `deck_accept_ownership`
* HTTP: `POST /api/actions/share.acceptOwnership`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.declineOwnership

**Decline ownership.** The pending owner declines the offer.

| Field          | Type    | Required | Description                                                      |
| -------------- | ------- | -------- | ---------------------------------------------------------------- |
| `id`           | string  | yes      |                                                                  |
| `baseRevision` | integer | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share decline-ownership <id>`
* MCP tool: `deck_decline_ownership`
* HTTP: `POST /api/actions/share.declineOwnership`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.claim

**Claim.** A signed in principal claims an unowned deck (an admin any unowned deck); the deck then reads Anyone with the address can view, so every view link and the embed keep working while editing by address stops.

| Field          | Type    | Required | Description                                                      |
| -------------- | ------- | -------- | ---------------------------------------------------------------- |
| `id`           | string  | yes      |                                                                  |
| `baseRevision` | integer | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share claim <id>`
* MCP tool: `deck_claim`
* HTTP: `POST /api/actions/share.claim`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## share.emailCollaborators

**Email collaborators.** Sends a message to every collaborator or the named ones; declared this round and answers not implemented until round four.

| Field          | Type            | Required | Description                                                      |
| -------------- | --------------- | -------- | ---------------------------------------------------------------- |
| `id`           | string          | yes      |                                                                  |
| `to`           | "all" \| object | yes      |                                                                  |
| `message`      | string          | yes      |                                                                  |
| `baseRevision` | integer         | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide share email <id> --message <message>`
* MCP tool: `deck_email_collaborators`
* HTTP: `POST /api/actions/share.emailCollaborators`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## deck.publish

**Publish to the web.** Mints the published player’s token and answers the player and embed URLs once; every edit is published, and the player never opens the editor.

| Field          | Type    | Required | Description                                                      |
| -------------- | ------- | -------- | ---------------------------------------------------------------- |
| `id`           | string  | yes      |                                                                  |
| `baseRevision` | integer | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide deck publish <id>`
* MCP tool: `deck_publish`
* HTTP: `POST /api/actions/deck.publish`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## deck.unpublish

**Stop publishing.** Revokes the published token; the player and the embed answer 410.

| Field          | Type    | Required | Description                                                      |
| -------------- | ------- | -------- | ---------------------------------------------------------------- |
| `id`           | string  | yes      |                                                                  |
| `baseRevision` | integer | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide deck unpublish <id>`
* MCP tool: `deck_unpublish`
* HTTP: `POST /api/actions/deck.unpublish`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.