strapi-plugin-radiocult-uploader 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Willis
+
+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,129 @@
+<p align="center">
+  <img src="./logo.png" alt="Strapi + Radio Cult" width="180">
+</p>
+
+# Radio Cult Uploader for Strapi
+
+Upload radio show episodes to [Radio Cult](https://www.radiocult.fm/) and publish them onward to **SoundCloud** and **Mixcloud** — straight from the Strapi admin.
+
+Built by [Sister Midnight FM](https://radio.sistermidnight.org/), a community radio station in South East London, for our own episode workflow — and made generic so any Radio Cult station running Strapi can use it.
+
+## What it does
+
+- **Uploader page** in the admin: pick an episode, drag in the audio file (`.mp3`/`.m4a`, up to Radio Cult's 750MB limit), watch a real progress bar, and the track lands in your Radio Cult media library — with the episode's artwork embedded in the mp3's ID3 tag (Radio Cult has no artwork API; embedded art is the only way).
+- **One-click publish** to SoundCloud and Mixcloud through Radio Cult's Connect endpoints, with title, tags, description and artwork.
+- **Automatic link write-back**: when Radio Cult finishes transferring, the resulting SoundCloud/Mixcloud URLs are saved onto your episode entry automatically (checked every 10 minutes by a cron sweep, on page polls, and on demand). Publishes done by hand in the Radio Cult dashboard are picked up too.
+- **Edit-view side panel** on your episode content type showing upload/publish state, with a button to open the uploader.
+- **Title sync**: renaming an episode in Strapi renames the Radio Cult track.
+- **Works with *your* content model**: a settings page maps your own content type and field names — nothing is imposed on your schema, and the plugin keeps its bookkeeping in its own hidden content type.
+- **Themeable**: colour presets, a handful of colour overrides, a font (system or Google Fonts) and your own logo on the uploader page.
+
+## Requirements
+
+- Strapi **v5**
+- Node **20+** (uploads stream files with `fs.openAsBlob`)
+- A Radio Cult station with API access; third-party publishing (SoundCloud/Mixcloud) needs a Radio Cult plan that includes the Connect endpoints (Premium/Business or the Connect add-on)
+
+## Installation
+
+```bash
+npm install strapi-plugin-radiocult-uploader
+# or: yarn add strapi-plugin-radiocult-uploader
+```
+
+Then **raise the request body limit** so full-size episodes can reach the plugin — Strapi's default is 200MB. In `config/middlewares.ts` (or `.js`), replace the `'strapi::body'` line with:
+
+```ts
+{
+  name: 'strapi::body',
+  config: {
+    formidable: {
+      maxFileSize: 800 * 1024 * 1024, // Radio Cult accepts up to 750MB
+    },
+  },
+},
+```
+
+Rebuild the admin (`npm run build`) and restart Strapi.
+
+## Setup
+
+Open **Settings → Radio Cult Uploader → Configuration**:
+
+1. **Credentials** — paste your Radio Cult **API key** and **station ID**, then hit **Test connection**.
+   Prefer environment variables in production: `RADIOCULT_API_KEY`, `RADIOCULT_STATION_ID` and `RADIOCULT_ENABLED` always override what's stored here (the fields grey out when the env vars are set).
+2. **Field mapping** — pick the content type your episodes live in. The plugin auto-matches fields by name and type; check them:
+
+   | Mapping | Field type | Used for |
+   |---|---|---|
+   | Title *(required)* | string/text | Track title on Radio Cult |
+   | Artwork image | media | Embedded in mp3s, sent to publishes |
+   | Broadcast date | date/datetime | Default album name, e.g. "August 2026" |
+   | SoundCloud link | string/text | The published URL is written here |
+   | Mixcloud link | string/text | The published URL is written here |
+   | Tags/genres relation | relation | Entries become publish tags (pick the label field too) |
+   | Show relation | relation | Optional — names the uploader browser tab |
+
+3. **Publish defaults** — default artist (your station name) and default publish description.
+4. **Uploader theme** — pick a preset (Paper, Midnight, Slate), a font (the system font or one of the bundled Google Fonts), tweak the six main colours, and set a station name and a logo (upload the logo in the Media Library and paste its URL). The preview updates live.
+   Google Fonts are fetched from `fonts.googleapis.com` / `fonts.gstatic.com` when a Google font is selected. If you have tightened `strapi::security`'s CSP, add those hosts to `style-src` and `font-src`, or stay on **System default**.
+5. Check **Diagnostics** at the bottom — it warns if your Node version or body-size limit will block uploads, or if cron is disabled.
+
+### Permissions
+
+Any admin with access to your episode content type can use the uploader. The settings page is guarded by a dedicated permission — grant **Radio Cult Uploader → Access the settings** to non-super-admin roles under *Settings → Roles → Plugins*.
+
+## Using it
+
+1. Open an episode in the Content Manager. The **Upload to Soundcloud/Mixcloud/Radio Cult** panel sits on the right (entries must be saved first).
+2. **Open Episode Uploader** → a themed page opens with three steps:
+   1. **Track details** — prefilled from the entry (title, artist, album, tags, description, artwork preview); edit freely, your Strapi entry is never changed by this form.
+   2. **Upload to Radio Cult** — drop the audio file in. mp3s get the artwork embedded. Re-uploading asks before replacing the existing track.
+   3. **Publish** — one button per platform. Radio Cult transfers asynchronously; the page polls and the link is written to your mapped link fields automatically. "Check for links now" forces a fresh look.
+3. The activity log at the bottom keeps a timestamped record of everything that happened.
+
+## Notes & limitations
+
+- **One station per Strapi instance.** The plugin talks to a single Radio Cult station.
+- **Mixcloud publishes may 402.** Radio Cult's docs say 402 means "not on your plan", but their Mixcloud endpoint has been observed returning `402 Internal server error` for *every* request even on plans where SoundCloud publishing works — a fault on Radio Cult's side. If that happens: publish the track by hand in the Radio Cult dashboard (Media → the track → Actions → Upload to Mixcloud). The plugin still detects the finished publish and saves the link to your entry (it watches recently uploaded tracks for up to 7 days).
+- **m4a artwork**: artwork can only be embedded into mp3 files; m4a uploads reach Radio Cult without an image.
+- **Artwork formats**: jpeg/png only; ≤10MB for embedding, ≤2MB for SoundCloud/Mixcloud publish artwork (the plugin picks the largest fitting size Strapi has generated).
+- **Rate limits**: Radio Cult 429s are respected with automatic backoff; the UI tells you when to retry.
+- **Draft & Publish**: link write-back writes directly to the stored entry (no publish cycle is triggered, and no other fields are touched).
+- The plugin registers a **cron job** (`*/10 * * * *`) for link syncing — make sure cron is enabled in `config/server.ts` (`cron: { enabled: true }`) if you want links to land while nobody has the page open.
+
+## Migrating from a pre-plugin setup
+
+If you previously wired Radio Cult uploads into your app with bookkeeping fields on your own content type (`RadioCultTrackId`, `RadioCultUploadedAt`, …), a migration script ships in the plugin repository:
+
+```bash
+RCU_DRY_RUN=true node scripts/migrate-from-fields.mjs   # from the plugin repo, run at your app root
+node scripts/migrate-from-fields.mjs
+```
+
+It copies the old field values into the plugin's track-records (see the script header for the env vars that change the source content type/field names). Afterwards you can delete the old fields from your schema.
+
+## Environment variables
+
+| Variable | Effect |
+|---|---|
+| `RADIOCULT_API_KEY` | Radio Cult API key (overrides the settings page) |
+| `RADIOCULT_STATION_ID` | Radio Cult station ID (overrides the settings page) |
+| `RADIOCULT_ENABLED` | `false` switches the whole integration off |
+
+## Development
+
+```bash
+npm install
+npm run build        # build admin + server bundles
+npm run watch:link   # develop against a local Strapi app via yalc
+npm run verify       # pre-publish checks
+```
+
+## License
+
+[MIT](./LICENSE)
+
+## Issues
+
+Bugs and feature requests: [GitHub issues](https://github.com/SisterMidnightFM/Strapi-to-Radio-Cult-Plugin/issues).