@single-studio/plugin-sheets 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Shaun Delaney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @single-studio/plugin-sheets
+
+A Google Sheet as a data source for
+[Single Studio](https://fourcourtjester.github.io/Single-Studio/) — a standings table,
+a roster, a running order — with an API key and no backend.
+
+```bash
+npm i @single-studio/plugin-sheets
+```
+
+```js
+import { sheets, GoogleSheetsHandler } from '@single-studio/plugin-sheets'
+
+// Which sheet, and which cells, are the *studio's* — see below.
+const SHEET = { id: '1AbC…', range: 'Standings!A1:D20' }
+
+class MyShow extends GoogleSheetsHandler {
+  onRows({ rows }) {
+    this.mutate('replace', { prefix: 'standings', members: rows })
+  }
+}
+
+createVelcroHost({ name: STUDIO_ID, mutations, plugins: [sheets(MyShow, SHEET)] })
+```
+
+The first row becomes column names by default, so a heading of `Team Name` reaches
+your graphics as `teamName`.
+
+## What the operator sets, and what you set
+
+The operator's board asks for **an API key** and **how often to read**. That is
+deliberately all of it.
+
+The **spreadsheet id and range are yours**, passed to the factory. A range is not a
+preference: your graphics have code expecting columns in an order, and a range that
+does not match does not show a different view of the same data — it shows the wrong
+column, confidently, with no error anywhere. Both are also already decided by the time
+anyone opens the panel, so offering them is offering a choice that has been made.
+
+## The key
+
+Share the sheet as **anyone with the link can view**, then create an API key with the
+Sheets API enabled.
+
+`type: 'secret'` masks the field on the board. It does not hide the key at runtime —
+the request is made from the browser, so it is in the network tab of the machine
+running the board. The protection is **restriction, not concealment**: limit the key
+to the Sheets API in the Cloud console, and add an HTTP referrer restriction where the
+studio is served from a known origin.
+
+What it does solve is the failure that actually happens — a key compiled into a bundle
+and sitting on a public `gh-pages` branch for a year.
+
+## Reading
+
+Only one machine in a room polls, and an unchanged answer says nothing at all — so a
+read that finds no change costs one request and no document write. Five seconds is the
+floor, whatever is typed; Google allows sixty reads a minute.
+
+A refusal stops rather than retrying, because a private sheet stays private however
+many times it is asked. A dropped network retries, because that is what backoff is
+for.
+
+## Licence
+
+MIT.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@single-studio/plugin-sheets",
+  "version": "0.6.0",
+  "description": "Google Sheets for Single Studio: a shared spreadsheet as a data source, with an API key and no backend.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FourCourtJester/Single-Studio.git",
+    "directory": "packages/plugin-sheets"
+  },
+  "homepage": "https://github.com/FourCourtJester/Single-Studio#readme",
+  "bugs": "https://github.com/FourCourtJester/Single-Studio/issues",
+  "type": "module",
+  "keywords": [
+    "single-studio",
+    "single-studio-plugin",
+    "obs",
+    "broadcast"
+  ],
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@single-studio/core": "^0.6.0"
+  },
+  "devDependencies": {
+    "@single-studio/core": "workspace:*",
+    "vitest": "^3.2.6"
+  }
+}

package/src/index.js

@@ -0,0 +1,140 @@
+import { definePlugin, PluginHandler, PollingService } from '@single-studio/core/worker'
+
+import { explain, parse, urlFor } from './sheet.js'
+
+export { explain, keyOf, parse, same, urlFor } from './sheet.js'
+
+/**
+ * A shared spreadsheet as a data source.
+ *
+ * The one people actually ask for. A spreadsheet is the tool a production team
+ * already has and already knows: the roster, the running order, the standings, the
+ * lower-third copy for the night. Somebody who will never open a code editor will
+ * happily keep a sheet up to date, and it is collaborative for free.
+ *
+ * Unlike the others this does not push. There is no socket and no notification, so
+ * it asks on a timer -- and everything about the design follows from wanting to ask
+ * as rarely as possible and to say nothing when the answer has not changed.
+ *
+ * **The ownership predicate matters most here.** Five operators each polling the
+ * same sheet is five times the quota and five writers racing on the same paths, for
+ * one sheet's worth of information. `Service` already answers that: exactly one
+ * machine asks, and everybody else reads the replicated result.
+ */
+class GoogleSheets extends PollingService {
+  static serviceName = 'google-sheets'
+
+  /** Google allows sixty reads a minute per user. One a second is a limit waiting. */
+  get floorSeconds() {
+    return 5
+  }
+
+  async read(signal) {
+    // Handed to `fetch` so the deadline actually stops the request. The base class
+    // enforces it either way, but without this the abandoned request keeps running
+    // and the next tick's poll queues up behind somebody else's stalled socket.
+    const response = await fetch(urlFor({ id: this.config.id, range: this.config.range, key: this.config.key }), { signal })
+    const body = await response.json().catch(() => ({}))
+
+    if (!response.ok) {
+      const problem = new Error(explain(response.status, body))
+
+      // Marked so `fatal` can tell a refusal from a dropped network without
+      // matching on the message text.
+      problem.refused = true
+      problem.status = response.status
+
+      throw problem
+    }
+
+    return parse(body, { header: this.config.header !== false })
+  }
+
+  /**
+   * A refusal is not something a retry fixes: a private sheet stays private however
+   * many times it is asked, and retrying only spends quota to be refused again. A
+   * dropped network is the opposite.
+   */
+  fatal(error) {
+    return Boolean(error?.refused)
+  }
+
+  /** The status is what a handler wants; the sentence is what a board shows. */
+  problemOf(error) {
+    return { status: error?.status ?? null, message: error?.message ?? String(error) }
+  }
+
+  /** `rows` rather than the base class's `changed`, because that is what it is. */
+  publish(next) {
+    this.emit('rows', { rows: next.rows, header: next.header, count: next.count })
+  }
+}
+
+/** The skeleton a studio fills in. */
+export class GoogleSheetsHandler extends PluginHandler {
+  static handles = { rows: 'onRows', problem: 'onProblem' }
+
+  onRows() {}
+
+  onProblem() {}
+}
+
+/**
+ * @param {typeof GoogleSheetsHandler} [Handler]
+ * @param {{ id?: string, range?: string, header?: boolean }} [sheet]
+ *   Which spreadsheet, and which cells. **Given by the studio, not by the operator.**
+ *
+ *   A range is not a preference. The studio reading it has code that expects columns
+ *   in an order, and a range that does not match is not a different view of the same
+ *   data -- it is a graphic quietly showing the wrong column, which is the worst way
+ *   for this to fail. The same goes for the id: a studio ships knowing the shape of
+ *   the sheet it was written against.
+ *
+ *   So the operator is asked for the one thing that is genuinely theirs and cannot
+ *   be shipped -- an API key, which is a credential.
+ */
+export const sheets = (Handler = GoogleSheetsHandler, sheet = {}) =>
+  definePlugin({
+    name: 'sheets',
+    label: 'Google Sheet',
+    summary: 'Reads a spreadsheet, so anybody on the team can update the show from a browser.',
+    help: [
+      { type: 'text', text: 'Two things are needed: the sheet has to be readable by anyone with its link, and you need a Google API key.' },
+      {
+        type: 'steps',
+        items: [
+          'Open the sheet, press Share, and set General access to "Anyone with the link" as a Viewer.',
+          'Go to console.cloud.google.com, make a project if you have none, and enable the Google Sheets API for it.',
+          'Under APIs & Services → Credentials, create an API key and paste it above.',
+        ],
+      },
+      {
+        type: 'note',
+        text: 'Which sheet this reads, and which cells, come from the studio rather than from here. They have to match the graphics that read them, so they are not something to change during a show.',
+      },
+      { type: 'link', href: 'https://console.cloud.google.com/apis/credentials', label: 'Google Cloud credentials' },
+      {
+        type: 'note',
+        text: 'The key only ever reads, and only what the sheet’s own sharing already allows. It is worth restricting it to the Sheets API in the Cloud console.',
+      },
+      { type: 'text', text: 'The first row is used as column names by default, so a heading of "Team Name" becomes teamName in your graphics.' },
+    ],
+    config: [
+      {
+        key: 'key',
+        label: 'API key',
+        type: 'secret',
+        help: 'A Google API key with the Sheets API enabled. The sheet must be shared as “anyone with the link can view”.',
+      },
+      { key: 'every', label: 'Read every (seconds)', type: 'number', default: 10, help: 'Five is the floor. Google allows sixty reads a minute.' },
+    ],
+    create: (context) => {
+      // The studio's sheet wins over anything stored, because there is nowhere to
+      // store it from -- these are not fields on the panel.
+      const plugin = new GoogleSheets({ ...context, config: { ...context.config, ...sheet } })
+
+      new Handler({ ...context, plugin }).attach(plugin.events)
+
+      return plugin
+    },
+  })

package/src/sheet.js

@@ -0,0 +1,124 @@
+// A Google Sheets response, turned into rows a studio can use.
+//
+// Pure, so the whole shape of the thing is testable without a network, an API key,
+// or a spreadsheet. What is left in the plugin is the polling.
+//
+// Sheets is unlike the other feeds in one way that decides the design: it does not
+// push. There is no socket and no notification, so the plugin asks on a timer, and
+// every design choice here follows from wanting to ask as rarely as possible and
+// say nothing when the answer has not changed.
+
+/**
+ * The API omits trailing empty cells rather than padding them, so a row whose last
+ * two columns are blank comes back short. Reading by index then silently shifts
+ * every value left of a gap.
+ *
+ * @param {string[][]} values
+ * @param {number} width
+ */
+const rectangular = (values, width) => values.map((row) => Array.from({ length: width }, (_, index) => row?.[index] ?? ''))
+
+/** The width of the widest row, which is the only honest column count. */
+const widthOf = (values) => values.reduce((widest, row) => Math.max(widest, row?.length ?? 0), 0)
+
+/**
+ * A header cell as a key somebody would type.
+ *
+ * `Team Name` becomes `teamName`, because a graphic writing `row['Team Name']` is a
+ * graphic that breaks when somebody tidies the capitalisation of a spreadsheet.
+ */
+export const keyOf = (label, index) => {
+  const cleaned = String(label ?? '')
+    .trim()
+    .replace(/[^a-zA-Z0-9]+(.)?/g, (_match, next) => (next ? next.toUpperCase() : ''))
+
+  const key = cleaned.charAt(0).toLowerCase() + cleaned.slice(1)
+
+  // An unnamed column still needs a name, or two of them collide on ''.
+  return key || `column${index + 1}`
+}
+
+/**
+ * Turn `{ values: [...] }` into rows.
+ *
+ * @param {object} body The API response.
+ * @param {object} [options]
+ * @param {boolean} [options.header] Treat the first row as column names.
+ * @returns {{ rows: Array<object|string[]>, header: string[]|null, count: number }}
+ */
+export function parse(body, { header = true } = {}) {
+  const values = Array.isArray(body?.values) ? body.values : []
+
+  if (!values.length) return { rows: [], header: header ? [] : null, count: 0 }
+
+  const width = widthOf(values)
+  const grid = rectangular(values, width)
+
+  if (!header) return { rows: grid, header: null, count: grid.length }
+
+  const [labels, ...rest] = grid
+  const keys = labels.map(keyOf)
+
+  // A row that is entirely blank is a spacer somebody left in the sheet, not a
+  // record. Emitting it puts an empty name on air.
+  const rows = rest
+    .filter((row) => row.some((cell) => String(cell).trim() !== ''))
+    .map((row) => Object.fromEntries(keys.map((key, index) => [key, row[index] ?? ''])))
+
+  return { rows, header: keys, count: rows.length }
+}
+
+/**
+ * Whether two parses differ.
+ *
+ * The reason the plugin can poll often without costing anything: an unchanged sheet
+ * emits nothing, so a studio's handler -- and every mutation it would make -- runs
+ * only when somebody has actually edited something.
+ *
+ * A string compare rather than a deep walk, because the values are strings from a
+ * spreadsheet and the arrays are small. Anything cleverer would be slower.
+ */
+export const same = (a, b) => JSON.stringify(a) === JSON.stringify(b)
+
+/**
+ * The URL to ask.
+ *
+ * An API key rather than OAuth, which is what makes this work with no backend: a
+ * sheet shared as "anyone with the link can view" is readable with a key, and a key
+ * is restrictable by referrer rather than being a secret to keep.
+ *
+ * @param {object} options
+ * @param {string} options.id The spreadsheet id, from its URL.
+ * @param {string} options.range A1 notation, e.g. `Standings!A1:D20`.
+ * @param {string} options.key
+ */
+export function urlFor({ id, range, key }) {
+  if (!id) throw new Error('A spreadsheet id is needed.')
+  if (!key) throw new Error('A Google API key is needed.')
+
+  const where = encodeURIComponent(range || 'A:Z')
+
+  // `UNFORMATTED_VALUE` would hand back numbers and serial dates, which is worse
+  // for a broadcast: what the operator typed in the cell is what they expect to see
+  // on air, currency symbols and all.
+  return `https://sheets.googleapis.com/v4/spreadsheets/${encodeURIComponent(id)}/values/${where}?key=${encodeURIComponent(key)}&valueRenderOption=FORMATTED_VALUE`
+}
+
+/**
+ * What a failed request means, in words an operator can act on.
+ *
+ * Google's messages are accurate and unhelpful at the moment something is wrong on
+ * a show -- "The caller does not have permission" does not say that the fix is one
+ * sharing setting.
+ */
+export function explain(status, body) {
+  const detail = body?.error?.message ?? ''
+
+  if (status === 403 && /API key not valid/i.test(detail)) return 'That API key was refused. Check it, and that the Sheets API is enabled for its project.'
+  if (status === 403) return 'Google refused the request. The sheet has to be shared as "anyone with the link can view".'
+  if (status === 404) return 'No spreadsheet with that id. Check the id in the sheet’s URL.'
+  if (status === 400 && /Unable to parse range/i.test(detail)) return 'That range was not understood. Use A1 notation, like Standings!A1:D20.'
+  if (status === 429) return 'Google is rate limiting this key. Poll less often.'
+
+  return detail || `Google answered ${status}.`
+}