From 5e36f51109c079d467cd2a937827c3c16bc28b65 Mon Sep 17 00:00:00 2001 From: trwnh Date: Tue, 30 Jun 2020 20:13:20 -0500 Subject: [PATCH] update for 3.1.4 (#786) * update for 3.1 * 3.1.2 * 3.1.3 * 3.1.4 --- content/en/admin/tootctl.md | 38 +++++++- content/en/entities/instance.md | 6 ++ content/en/methods/instance.md | 1 + content/en/methods/statuses/media.md | 132 +++++++++++++++++++++++++++ content/en/methods/timelines.md | 4 + 5 files changed, 180 insertions(+), 1 deletion(-) diff --git a/content/en/admin/tootctl.md b/content/en/admin/tootctl.md index 71e294fb..7fae1f37 100644 --- a/content/en/admin/tootctl.md +++ b/content/en/admin/tootctl.md @@ -87,6 +87,7 @@ Modify a user account's role, email, active status, approval mode, or 2FA requir **Version history:** * 2.6.0 - added +* 3.1.2 - added `--reset-password` | Option | Description | | :--- | :--- | @@ -97,7 +98,8 @@ Modify a user account's role, email, active status, approval mode, or 2FA requir | `--disable` | Lock USERNAME out of their account. | | `--enable` | Unlock USERNAME's account if it is currently disabled. | | `--approve` | Approve the account, if you are/were in approval mode. | -| `--disable_2fa` | Remove additional factors and allow login with password. | +| `--disable-2fa` | Remove additional factors and allow login with password. | +| `--reset-password` | Resets the password of the given account. | ### `tootctl accounts delete` {#accounts-delete} @@ -268,6 +270,19 @@ Crawl the known fediverse by using Mastodon REST API endpoints that expose all k {{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/emoji_cli.rb" caption="lib/mastodon/emoji\_cli.rb" >}} +### `tootctl emoji export` {#emoji-export} + +Exports custom emoji to `export.tar.gz` at PATH. + +**Version history:** +* 3.1.4 - added + +| Option | Description | +| :--- | :--- | +| `PATH` | Path to create a .tar.gz archive containing pictures. | +| `--overwrite` | Overwrite the existing archive. | +| `--category CATEGORY` | Export only the specified CATEGORY. If not provided, will export all emoji. | + ### `tootctl emoji import` {#emoji-import} Imports custom emoji from a .tar.gz archive at a given path. The archive should contain PNG or GIF files no larger than 50KB, and the shortcode will be set equal to the filename minus the extension, with optional prefixes and/or suffixes. @@ -347,11 +362,13 @@ Scans for files that do not belong to existing media attachments, and remove the **Version history:** * 3.1.0 - added +* 3.1.3 - added `--prefix` | Option | Description | | :--- | :--- | | `--start_after` | The Paperclip attachment key where the loop will start. Use this option if the command was interrupted before. | | `--dry_run` | Print expected results only, without performing any actions. | +| `--prefix` | Traverse only a specific prefix of files in the system. | ### `tootctl media refresh` {#media-refresh} @@ -450,8 +467,27 @@ This is a computationally heavy procedure that creates extra database indices be **Version history:** * 2.8.0 - added +* 3.1.3 - added `--skip-media-remove` | Option | Description | | :--- | :--- | | `--days` | How old statuses have to be before they are removed. Defaults to 90. | +| `--skip-media-remove` | Skips removing the media, in case S3 errors out. Defaults to false. | + +## Upgrade CLI {#upgrade} + +{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/statuses_cli.rb" caption="lib/mastodon/upgrade\_cli.rb" >}} + +### `tootctl upgrade storage-schema` {#upgrade-storage-schema} + +Upgrade the storage schema to store all non-local media resources in a top-level cache directory. WARNING: This is optional, and only for deployments made before v3.1.4. This command can incur massive object storage costs due to moving potentially terabytes of data. + +**Version history:** +* 3.1.4 - added + +| Option | Description | +| :--- | :--- | +| `--verbose` | Print additional information while task is processing. | +| `--dry_run` | Print expected results only, without performing any actions. | + diff --git a/content/en/entities/instance.md b/content/en/entities/instance.md index 7e80687c..97aa7d82 100644 --- a/content/en/entities/instance.md +++ b/content/en/entities/instance.md @@ -121,6 +121,12 @@ menu: **Type:** Boolean\ **Version history:** Added in 2.9.2 +### `invites_enabled` {#invites_enabled} + +**Description:** Whether invites are enabled.\ +**Type:** Boolean\ +**Version history:** Added in 3.1.4 + ### `urls` {#urls} **Description:** URLs of interest for clients apps.\ diff --git a/content/en/methods/instance.md b/content/en/methods/instance.md index aa6f1276..06a33251 100644 --- a/content/en/methods/instance.md +++ b/content/en/methods/instance.md @@ -19,6 +19,7 @@ Information about the server. - 1.1.0 - added - 3.0.0 - requires user token if instance is in whitelist mode +- 3.1.4 - added `invites_enabled` to response {{< endapi-method-description >}} {{< api-method-spec >}} diff --git a/content/en/methods/statuses/media.md b/content/en/methods/statuses/media.md index 5a8d3f28..1b12d324 100644 --- a/content/en/methods/statuses/media.md +++ b/content/en/methods/statuses/media.md @@ -20,6 +20,7 @@ Creates an attachment to be used with a new status. - 0.0.0 - added - 2.3.0 - add `focus` parameter +- 3.1.3 - deprecated in favor of `POST /api/v2/media`, which is equal to v1 in all aspects, except it returns HTTP 202, and the returned JSON object has a url of null, because while the thumbnail is prepared synchronously, the full version of the media attachment will be processed in the background {{< endapi-method-description >}} {{< api-method-spec >}} @@ -134,6 +135,137 @@ File or file type is unsupported or invalid {{< endapi-method-response >}} {{< endapi-method-spec >}} {{< endapi-method >}} + + +{{< api-method method="get" host="https://mastodon.example" path="/api/v1/media/:id" title="Update attachment" >}} +{{< api-method-description >}} + +Get an Attachment, before it is attached to a status and posted, but after it is accepted for processing. + +**Returns:** Attachment\ +**OAuth:** User token + `write:media`\ +**Version history:** + +- 3.1.3 - added + +{{< endapi-method-description >}} +{{< api-method-spec >}} +{{< api-method-request >}} +{{< api-method-path-parameters >}} +{{< api-method-parameter name=":id" type="string" required=true >}} +The id of the Attachment entity to be updated +{{< endapi-method-parameter >}} +{{< endapi-method-path-parameters >}} +{{< api-method-headers >}} +{{< api-method-parameter name="Authorization" type="string" required=true >}} +Bearer <user token> +{{< endapi-method-parameter >}} +{{< endapi-method-headers >}} +{{< api-method-form-data-parameters >}} +{{< api-method-parameter name="file" type="object" required=false >}} +The file to be attached, using multipart form data. +{{< endapi-method-parameter >}} +{{< api-method-parameter name="description" type="string" required=false >}} +A plain-text description of the media, for accessibility purposes. +{{< endapi-method-parameter >}} +{{< api-method-parameter name="focus" type="string" required=false >}} +Two floating points \(x,y\), comma-delimited ranging from -1.0 to 1.0 +{{< endapi-method-parameter >}} +{{< endapi-method-form-data-parameters >}} +{{< endapi-method-request >}} +{{< api-method-response >}} +{{< api-method-response-example httpCode=200 >}} +{{< api-method-response-example-description >}} +Attachment has been processed +{{< endapi-method-response-example-description >}} + + +```javascript +{ + "id": "22348641", + "type": "image", + "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/e96382f26c72a29c.jpeg", + "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/e96382f26c72a29c.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", + "meta": { + "focus": { + "x": -0.42, + "y": 0.69 + }, + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + } + }, + "description": "test uploaded via api, but updated", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" +} +``` +{{< endapi-method-response-example >}} +{{< api-method-response-example httpCode=206 >}} +{{< api-method-response-example-description >}} + +Attachment is not yet ready +{{< endapi-method-response-example-description >}} + + +```javascript + +``` +{{< endapi-method-response-example >}} +{{< api-method-response-example httpCode=401 >}} +{{< api-method-response-example-description >}} + +Invalid or missing Authorization header +{{< endapi-method-response-example-description >}} + + +```javascript +{ + "error": "The access token is invalid" +} +``` +{{< endapi-method-response-example >}} +{{< api-method-response-example httpCode=404 >}} +{{< api-method-response-example-description >}} + +Attachment does not exist, is deleted, or was not created by you +{{< endapi-method-response-example-description >}} + + +```javascript +{ + "error": "Record not found" +} +``` +{{< endapi-method-response-example >}} +{{< api-method-response-example httpCode=422 >}} +{{< api-method-response-example-description >}} + +Error processing the media attachment +{{< endapi-method-response-example-description >}} + + +```javascript +{ + "error": "Validation failed: File content type is invalid, File is invalid" +} +``` +{{< endapi-method-response-example >}} +{{< endapi-method-response >}} +{{< endapi-method-spec >}} +{{< endapi-method >}} + + {{< api-method method="put" host="https://mastodon.example" path="/api/v1/media/:id" title="Update attachment" >}} {{< api-method-description >}} diff --git a/content/en/methods/timelines.md b/content/en/methods/timelines.md index 8cbe6898..f182d79b 100644 --- a/content/en/methods/timelines.md +++ b/content/en/methods/timelines.md @@ -19,6 +19,7 @@ menu: - 2.3.0 - added `only_media` - 2.6.0 - add `min_id` - 3.0.0 - auth is required if public preview is disabled +- 3.1.4 - added `remote` {{< endapi-method-description >}} {{< api-method-spec >}} @@ -27,6 +28,9 @@ menu: {{< api-method-parameter name="local" type="boolean" required=false >}} Show only local statuses? Defaults to false. {{< endapi-method-parameter >}} +{{< api-method-parameter name="remote" type="boolean" required=false >}} +Show only remote statuses? Defaults to false. +{{< endapi-method-parameter >}} {{< api-method-parameter name="only_media" type="boolean" required=false >}} Show only statuses with media attached? Defaults to false. {{< endapi-method-parameter >}}