From 4f22f780fb35deab7c2b97d50a8d5e8b0f85c50c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 8 Apr 2019 21:13:30 -0600 Subject: [PATCH 1/3] Proposal for a sticker picker API --- proposals/0000-integrations-stickerpicker.md | 84 ++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 proposals/0000-integrations-stickerpicker.md diff --git a/proposals/0000-integrations-stickerpicker.md b/proposals/0000-integrations-stickerpicker.md new file mode 100644 index 00000000000..d7e2a779259 --- /dev/null +++ b/proposals/0000-integrations-stickerpicker.md @@ -0,0 +1,84 @@ +# MSC0000: Sticker picker API + +[MSC1951 - Custom sticker packs and emojis](https://github.com/matrix-org/matrix-doc/pull/1951) adds a way +for pack authors to share their creations with other users, however the interaction between them and the +sticker/emoji pickers themselves are not defined. Although this proposal does not include an emoji picker +definition, the API it proposes can easily and transparently be extended to such a widget. + + +## Proposal + +Some clients may wish to not embed the sticker picker widget into their application and instead get the sticker +packs and render them as one common picker. To do this, the client would use the `api_url` specified in the +widget's `data`. If the `api_url` is a trusted integration manager, the client should make requests to the API +endpoints defined in this proposal using +[MSC0000 - Integration manager authentication](https://github.com/matrix-org/matrix-doc/pull/0000). If the +URL is not trusted, the user should be prompted for approval or the sticker picker skipped by the client. + +#### GET /_matrix/integrations/v1/widgets/{widgetId}/packs + +Retrieves the packs (as defined by MSC1951) for the sticker picker. In future, this API could be used by an +emoji picker widget if it were to exist. No additional information is required to make the request, besides +authorization tokens. The token should belong to the user which also owns the picker widget. + +An example response is: +```json +{ + "packs": [ + { + "kind": "m.stickers", + "name": "My Cool Stickerpack", + "description": "This is the topic from the pack's room", + "thumbnail": "mxc://example.org/media_id", + "sharable_url": "https://packs.example.org/1234/my-cool-stickerpack", + "creator": "https://matrix.to/#/%40alice%3Aexample.org", + "author": "https://matrix.to/#/%40alice%3Aexample.org", + "license": "CC-BY-NC-SA-4.0", + "active_items": [ + { + "id": "ThisIsTheItemIdToDistinguishItFromAnotherItem-1", + "uri": "mxc://example.org/media_id", + "description": "This is where a short sentence explaining the sticker goes", + "shortcodes": [ + ":sample:", + ":cool_sticker:" + ] + }, + { + "id": "ThisIsTheItemIdToDistinguishItFromAnotherItem-2", + "uri": "mxc://example.org/media_id_2", + "description": "Words go here", + "shortcodes": [ + ":words:", + ":example:" + ] + } + ] + } + ] +} +``` + +Note that the pack object in the response is very similar to that of a `m.pack.metadata` event containing +`m.pack.item` events. The additional fields are `name` (required), `description` (optional), `thumbnail` +(optional - use first item's `uri` if not present), and `sharable_url` (required). The `active_items` +array has also been modified to be `m.pack.item` event contents with an added `id` field for tracking +purposes. + +#### PUT /_matrix/integrations/v1/widgets/{widgetId}/packs + +Adds a new pack to the picker. The picker is responsible for resolving the sharable URL provided and tracking +changes to it. The response is 200 OK with a pack object (see `GET` version of this API above). + +An example request body would be: +```json +{ + "sharable_url": "https://packs.example.org/1234/my-cool-stickerpack" +} +``` + +#### DELETE /_matrix/integrations/v1/widgets/{widgetId}/packs + +Similar to the `PUT` version, this deletes a pack from the picker. The picker is expected to resolve the +sharable URL provided to determine which pack needs to be removed. If the pack was removed, an empty +JSON object with 200 OK is returned. The request body is the same as the `PUT` version of this endpoint. From e3fe7ddb63f0d016c3dfe3fdf91e683fe039fdee Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 8 Apr 2019 21:15:45 -0600 Subject: [PATCH 2/3] Assign MSC number --- ...ions-stickerpicker.md => 1959-integrations-stickerpicker.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{0000-integrations-stickerpicker.md => 1959-integrations-stickerpicker.md} (99%) diff --git a/proposals/0000-integrations-stickerpicker.md b/proposals/1959-integrations-stickerpicker.md similarity index 99% rename from proposals/0000-integrations-stickerpicker.md rename to proposals/1959-integrations-stickerpicker.md index d7e2a779259..139a678e87e 100644 --- a/proposals/0000-integrations-stickerpicker.md +++ b/proposals/1959-integrations-stickerpicker.md @@ -1,4 +1,4 @@ -# MSC0000: Sticker picker API +# MSC1959: Sticker picker API [MSC1951 - Custom sticker packs and emojis](https://github.com/matrix-org/matrix-doc/pull/1951) adds a way for pack authors to share their creations with other users, however the interaction between them and the From 9be9d6d83cd20d7132d21446dd1508803d570971 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 8 Apr 2019 21:39:05 -0600 Subject: [PATCH 3/3] Fill in templated MSCs --- proposals/1959-integrations-stickerpicker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1959-integrations-stickerpicker.md b/proposals/1959-integrations-stickerpicker.md index 139a678e87e..aba21e61943 100644 --- a/proposals/1959-integrations-stickerpicker.md +++ b/proposals/1959-integrations-stickerpicker.md @@ -12,7 +12,7 @@ Some clients may wish to not embed the sticker picker widget into their applicat packs and render them as one common picker. To do this, the client would use the `api_url` specified in the widget's `data`. If the `api_url` is a trusted integration manager, the client should make requests to the API endpoints defined in this proposal using -[MSC0000 - Integration manager authentication](https://github.com/matrix-org/matrix-doc/pull/0000). If the +[MSC1961 - Integration manager authentication](https://github.com/matrix-org/matrix-doc/pull/1961). If the URL is not trusted, the user should be prompted for approval or the sticker picker skipped by the client. #### GET /_matrix/integrations/v1/widgets/{widgetId}/packs