Add media gallery plugin server

Author: cainwatson

media-gallery-plugin/.env.example

@@ -0,0 +1,2 @@
+PORT="3001"
+URL="http://localhost:3001"

media-gallery-plugin/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+.DS_Store
+.env

media-gallery-plugin/README.md

@@ -0,0 +1,43 @@
+# Kit Media Gallery Plugin Demo
+
+This directory serves as an example of how you can structure your application to respond
+to Kit's media gallery plugin framework.
+
+It contains a *list media* endpoint, which returns a list of paginated media items to
+display in the gallery. You can view the comments in `index.js` to learn more about the
+implementation.
+
+If you want to run this app locally, you can do so by running:
+
+```
+cp .env.example .env
+npm install
+npm run start
+```
+
+This endpoint assume that your plugin would be structured as follows on your [plugin
+settings](https://app.kit.com/account_settings/developer_settings).
+
+- **Plugin name:**
+  My Media
+
+- **Description:**
+  A media gallery plugin demo.
+
+- **HTML URL:**
+  https://YOUR_URL/media
+
+  > Replace `YOUR_URL` with your server's URL.
+
+- **Settings JSON:**
+
+  ```json
+  [
+    {
+      "type": "text",
+      "name": "query",
+      "help": "Search your media",
+      "required": false
+    }
+  ]
+  ```

media-gallery-plugin/index.js

@@ -0,0 +1,93 @@
+require('dotenv').config()
+const express = require('express')
+const {
+  search,
+  filter,
+  sort,
+  paginate,
+  find,
+  MEDIA_ITEMS,
+} = require('./media-generator')
+const app = express()
+const port = process.env.PORT || 3001
+
+app.use(express.json())
+
+/**
+ * Responds to request for listing media items.
+ * - Expects pagination query params: `after`, `before`, and `per_page`.
+ * - Expects search query param: `search.<setting name>` (configured in plugin settings)
+ * - Expects filter query params: `filters.<setting name>` (configured in plugin settings)
+ * - Expects sort query param: `sort.<setting name>` (configured in plugin settings)
+ */
+app.get('/media', (request, response) => {
+  console.log(request.query)
+
+  const searchedMedia = search(MEDIA_ITEMS, request.query.settings?.query)
+  const filteredMedia = filter(searchedMedia, request.query.settings || {})
+  const sortedMedia = sort(filteredMedia, request.query.settings || {})
+  const {
+    data: paginatedMedia,
+    perPage,
+    startCursor,
+    endCursor,
+    hasPreviousPage,
+    hasNextPage,
+  } = paginate(sortedMedia, {
+    after: request.query.after,
+    before: request.query.before,
+    perPage: Math.min(Number.parseInt(request.query.per_page || '100'), 1000),
+  })
+  const data = paginatedMedia.map(mediaItem => ({
+    id: mediaItem.id,
+    type: mediaItem.type,
+    alt: mediaItem.alt,
+    caption: mediaItem.caption,
+    title: mediaItem.title,
+    url: mediaItem.url,
+    thumbnail_url: mediaItem.thumbnail_url,
+    hotlink: mediaItem.hotlink,
+    attribution: mediaItem.attribution,
+    notify_download_url: mediaItem.notify_download_url,
+  }))
+
+  response.json({
+    data,
+    pagination: {
+      per_page: perPage,
+      start_cursor: startCursor,
+      end_cursor: endCursor,
+      has_previous_page: hasPreviousPage,
+      has_next_page: hasNextPage,
+    },
+  })
+})
+
+/**
+ * Responds to request that a media item was downloaded.
+ */
+app.post('/media/:id/downloaded', (request, response) => {
+  const media = find(request.url)
+  console.log(
+    `${media.title} ${media.url} ${request.params.id} was downloaded!`
+  )
+
+  response.sendStatus(204)
+})
+
+/**
+ * Responds to request for listing folder options for dynamic select setting
+ */
+app.get('/folders', (request, response) => {
+  response.json({
+    options: [
+      { label: 'Home', value: 'home' },
+      { label: 'Favorites', value: 'favorites' },
+      { label: 'Shared', value: 'shared' },
+    ],
+  })
+})
+
+app.listen(port, () => {
+  console.log(`Server running at :${port}`)
+})

media-gallery-plugin/media-generator.js

@@ -0,0 +1,132 @@
+const { faker } = require('@faker-js/faker')
+const Fuse = require('fuse.js')
+
+/**
+ * Fake media items. For a real plugin, this would come from a database or API.
+ */
+const MEDIA_ITEMS = faker.helpers.multiple(
+  () => {
+    const id = faker.string.nanoid()
+    return {
+      id,
+      type: 'image',
+      alt: faker.lorem.sentence(),
+      caption: faker.lorem.words(),
+      title: faker.system.commonFileName('jpg'),
+      url: faker.image.urlPicsumPhotos({
+        width: 600,
+        height: 900,
+        blur: 0,
+        grayscale: false,
+      }),
+      thumbnail_url: faker.image.urlPicsumPhotos({
+        width: 600,
+        height: 900,
+        blur: 0,
+        grayscale: false,
+      }),
+      hotlink: faker.datatype.boolean(),
+      ...(faker.datatype.boolean() && {
+        attribution: {
+          label: faker.person.fullName(),
+          href: `https://${faker.internet.domainName()}/abc?utm_source=your_app_name&utm_medium=referral`,
+        },
+      }),
+      ...(faker.datatype.boolean() && {
+        notify_download_url: `${process.env.URL}/media/${id}/downloaded`,
+      }),
+
+      labels: faker.helpers.arrayElement([
+        [],
+        ['my_content'],
+        ['my_content', 'favorite'],
+        ['shared'],
+      ]),
+      created_at: faker.date.anytime(),
+    }
+  },
+  { count: 2000 }
+)
+
+/**
+ * Searches for media items using query.
+ */
+function search(items, query) {
+  const fuse = new Fuse(items, {
+    threshold: 0.8,
+    keys: ['title', 'caption', 'attribution.label'],
+  })
+  if (query) {
+    return fuse.search(query).map(search => search.item)
+  }
+  return items
+}
+
+/**
+ * Filters for media items
+ */
+function filter(items, params) {
+  if (params.label) {
+    return items.filter(item => item.labels.includes(params.label))
+  }
+  return items
+}
+
+/**
+ * Sort for media items
+ */
+function sort(items, params) {
+  if (params.sort === 'alphabetical_asc') {
+    return items.slice().sort((a, b) => a.caption.localeCompare(b.caption))
+  } else if (params.sort === 'alphabetical_desc') {
+    return items.slice().sort((a, b) => a.caption.localeCompare(b.caption) * -1)
+  } else if (params.sort === 'created_asc') {
+    return items.slice().sort((a, b) => b.created_at - a.created_at)
+  } else if (params.sort === 'created_desc') {
+    return items.slice().sort((a, b) => (b.created_at - a.created_at) * -1)
+  }
+  return items
+}
+
+/**
+ * Paginates through media items. Uses limit/offset approach.
+ */
+function paginate(data, { before, after, perPage }) {
+  const decodedBefore =
+    before && Buffer.from(before, 'base64').toString('ascii')
+  const decodedAfter = after && Buffer.from(after, 'base64').toString('ascii')
+
+  let startCursor = 0
+
+  if (after) {
+    startCursor = Number.parseInt(decodedAfter)
+  } else if (before) {
+    startCursor = Number.parseInt(decodedBefore) - perPage
+  }
+
+  const pagedData = data.slice(startCursor, startCursor + perPage)
+
+  return {
+    data: pagedData,
+    perPage,
+    startCursor: Buffer.from(startCursor.toString()).toString('base64'),
+    endCursor: Buffer.from((startCursor + perPage).toString()).toString(
+      'base64'
+    ),
+    hasPreviousPage: startCursor > 0,
+    hasNextPage: startCursor + perPage <= data.length,
+  }
+}
+
+function find({ url }) {
+  return MEDIA_ITEMS.find(media => media.notify_download_url === url)
+}
+
+module.exports = {
+  MEDIA_ITEMS,
+  search,
+  filter,
+  sort,
+  paginate,
+  find,
+}