domma-cms 1.8.32 → 1.8.34

package/plugins/garage/collections/garage-vehicles/schema.json

@@ -0,0 +1,101 @@
+{
+  "slug": "garage-vehicles",
+  "title": "Garage Vehicles",
+  "description": "Vehicle registrations managed by the Garage plugin.",
+  "plugin": "garage",
+  "fields": [
+    {
+      "name": "userId",
+      "label": "User ID",
+      "type": "text",
+      "required": true
+    },
+    {
+      "name": "registrationNumber",
+      "label": "Registration",
+      "type": "text",
+      "required": true
+    },
+    {
+      "name": "make",
+      "label": "Make",
+      "type": "text"
+    },
+    {
+      "name": "colour",
+      "label": "Colour",
+      "type": "text"
+    },
+    {
+      "name": "yearOfManufacture",
+      "label": "Year",
+      "type": "text"
+    },
+    {
+      "name": "fuelType",
+      "label": "Fuel Type",
+      "type": "text"
+    },
+    {
+      "name": "engineCapacity",
+      "label": "Engine Capacity",
+      "type": "text"
+    },
+    {
+      "name": "co2Emissions",
+      "label": "CO2 Emissions",
+      "type": "text"
+    },
+    {
+      "name": "motStatus",
+      "label": "MOT Status",
+      "type": "text"
+    },
+    {
+      "name": "motExpiryDate",
+      "label": "MOT Expiry",
+      "type": "text"
+    },
+    {
+      "name": "taxStatus",
+      "label": "Tax Status",
+      "type": "text"
+    },
+    {
+      "name": "taxDueDate",
+      "label": "Tax Due",
+      "type": "text"
+    },
+    {
+      "name": "isSaved",
+      "label": "Saved",
+      "type": "text"
+    },
+    {
+      "name": "lookupDate",
+      "label": "Lookup Date",
+      "type": "text"
+    }
+  ],
+  "api": {
+    "create": {
+      "enabled": false,
+      "access": "admin"
+    },
+    "read": {
+      "enabled": false,
+      "access": "admin"
+    },
+    "update": {
+      "enabled": false,
+      "access": "admin"
+    },
+    "delete": {
+      "enabled": false,
+      "access": "admin"
+    }
+  },
+  "storage": {
+    "adapter": "file"
+  }
+}

package/plugins/garage/config.js

@@ -0,0 +1,18 @@
+/**
+ * Garage Plugin — Default Configuration
+ *
+ * Override any of these via config/plugins.json under "garage.settings".
+ */
+export default {
+    /** DVLA Vehicle Enquiry Service API key. Obtain from developer-portal.driver-vehicle-licensing.api.gov.uk */
+    dvlaApiKey: '',
+    /** DVLA API endpoint — do not change unless DVLA updates their URL. */
+    dvlaApiUrl: 'https://driver-vehicle-licensing.api.gov.uk/vehicle-enquiry/v1/vehicles',
+    /** Per-user rate limiting for the /lookup endpoint. */
+    rateLimit: {
+        max: 10,
+        windowSeconds: 60
+    },
+    /** Maximum lookup history entries to retain per user (oldest unsaved entries are pruned first). */
+    maxHistoryItems: 100
+};

package/plugins/garage/docs/guide.md

@@ -0,0 +1,118 @@
+---
+title: Guide
+order: 1
+---
+
+Garage looks up UK vehicles by registration using the DVLA's Vehicle Enquiry Service. Save the vehicles you care about to My Garage to see when their MOT and road tax are due, with reminders before they run out.
+
+## What it does
+
+- Type a UK registration and get the make, colour, year, fuel, engine size, CO2, and the MOT and road tax status with their dates.
+- Keeps every lookup in your **History**.
+- **My Garage** holds the vehicles you save, with the ones needing attention first.
+- The **Garage** sidebar badge counts saved vehicles that need attention.
+- Admin notifications when an MOT or road tax is due soon or has run out.
+- A shortcode to show one person's saved vehicles on a public page.
+
+Everything is per person. Nobody sees anyone else's lookups or saved vehicles.
+
+## Getting started
+
+Garage needs a DVLA Vehicle Enquiry Service API key, which the DVLA issues through its developer portal.
+
+1. Register on the DVLA developer portal (developer-portal.driver-vehicle-licensing.api.gov.uk) and request a Vehicle Enquiry Service API key.
+2. Open [Garage](#/plugins/garage) from the admin sidebar.
+3. Click the cog in the page banner (**Garage settings**), or **Add the key** in the warning.
+4. Paste the key into **DVLA API key** and click **Save key** (or press Enter). It works straight away; no restart is needed.
+5. Type a registration in the yellow plate box, for example `AB12 CDE`, and click **Look up** or press Enter.
+6. Click **Save to My Garage** to keep it.
+
+Saving the key needs permission to change plugin settings, which admins have. Once saved, everyone with Garage access uses the site's key.
+
+## Screens
+
+### Look up a vehicle
+
+- The result shows the plate, make and year, and two chips for MOT and tax.
+- **Save to My Garage** or **Remove from My Garage**.
+- **Details** lists Make, Year, Colour, Fuel, Engine, CO2, MOT, MOT expires, Road tax, Tax due and Last looked up.
+- Lookups are limited per person (10 a minute by default). If you hit the limit, the message says how many seconds to wait.
+
+### My Garage
+
+- **All** or **Needs attention**, and a search box for registration, make and colour.
+- Vehicles are sorted by urgency:
+  - Red: the MOT has expired or the tax has run out.
+  - Amber: the MOT or tax is due within 30 days, or the vehicle is SORN.
+- Click a vehicle for its details. Right-click it, or click its three-dot button, for:
+  - **Details...**
+  - **Look up again** - fetches fresh data from the DVLA
+  - **Remove from My Garage** or **Save to My Garage**
+  - **Copy registration**
+  - **Delete...**
+
+The dates are as the DVLA had them at the last lookup. Use **Look up again** after renewing tax or an MOT.
+
+### History
+
+- Every vehicle you have looked up, newest first. Looking one up again updates it rather than adding a copy.
+- Search with **Search history...**.
+- **Clear unsaved** deletes all lookups you have not saved. Vehicles in My Garage are kept.
+- Once your history passes 100 lookups, the oldest unsaved ones are dropped automatically.
+
+Deleting a vehicle removes it from both lists. Looking it up again brings it back.
+
+## Settings
+
+**Garage settings** (the banner cog) holds one setting: the **DVLA API key**. Once saved it is never shown again; type a new one to replace it. If whoever runs the site has set the `DVLA_API_KEY` environment variable, that key is used instead.
+
+Other options can only be changed in the plugin's configuration file:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `rateLimit.max` | 10 | Lookups allowed per person in the window |
+| `rateLimit.windowSeconds` | 60 | The window, in seconds |
+| `maxHistoryItems` | 100 | Lookups kept per person before the oldest unsaved are dropped |
+
+## Notifications
+
+Once a day, and when the site starts, Garage checks each person's saved vehicles and tells that person only:
+
+- MOT expired or tax run out - an urgent notification.
+- MOT or tax due within 30 days - a warning.
+
+SORN vehicles do not raise notifications. A notification clears itself at a later check once the saved dates are no longer due, so look the vehicle up again after renewing.
+
+## Shortcodes
+
+Show one person's saved vehicles as cards on a public page:
+
+```text
+[garage-vehicles user="USER-ID" /]
+```
+
+- `user` is required. Without it the shortcode shows nothing.
+- To find a person's user id, open System > Users and edit that person. The id is the last part of the address in the browser, after `#/users/edit/`.
+- Only vehicles saved to My Garage appear, not unsaved history.
+- Each card shows the plate, make and year, colour, fuel, engine size, CO2, and MOT and tax badges with their dates.
+- If the person has no saved vehicles, nothing is shown.
+
+Anyone who can see that page sees those vehicles. Only use it on pages meant for that.
+
+## Permissions and roles
+
+In System > Roles, Garage appears in the **Plugins** group:
+
+| Action | Label | Allows |
+|---|---|---|
+| `garage.read` | View | Open My Garage and your lookup history |
+| `garage.create` | Look up | Look vehicles up (uses the site's DVLA key) and save them |
+| `garage.delete` | Delete | Remove your saved vehicles and lookups |
+
+The **admin** and **user** roles get all three by default. Every lookup uses the site's DVLA key, so take **Look up** away from roles that should not spend it.
+
+## Limitations
+
+- UK registrations only, and only what the DVLA's Vehicle Enquiry Service returns. There is no MOT history, mileage or keeper information.
+- Data is not refreshed automatically. Statuses and dates are from the last lookup; the daily check works from those saved dates.
+- If the DVLA cannot be reached or does not know the registration, the lookup fails with a message and nothing is saved.