Payload Plugin Hyros Widget

Payload plugin that adds Hyros analytics widgets to the admin dashboard.

Current implementation includes:

• Individual drag-and-drop metric widgets (not one monolithic card)
• Chart-first widget visuals for trends, mix, and funnel snapshots
• Server-side Hyros API proxy endpoint (API key stays on server)

Features

Widget Collection

• Total Revenue
• Qualified Sales
• Refunds & Discounts
• Revenue Trend
• Product Mix
• Total Leads
• Leads Trend
• Lead Funnel
• Top Lead Tags

Installation

pnpm add @main12/payload-hyros-widget

Required Environment Variables

HYROS_API_KEY=your_hyros_api_key

For local development in this repository, configure dev/.env from dev/.env.example.

If you want to use a different environment variable name, pass hyrosApiKeyEnvVarName in the plugin options.

Usage

Add the plugin in your Payload config:

import { buildConfig } from 'payload'
import { payloadPluginHyrosWidget } from '@main12/payload-hyros-widget'

export default buildConfig({
  plugins: [
    payloadPluginHyrosWidget({
      defaultDateRangeDays: 30,
      collections: {
        posts: true,
      },
    }),
  ],
})

Plugin Options

type PayloadPluginHyrosWidgetConfig = {
  collections?: Partial<Record<CollectionSlug, true>>
  defaultDateRangeDays?: number
  hyrosApiKeyEnvVarName?: string
  widgetStyle?: 'default' | 'minimal'
  disabled?: boolean
}

• collections: optionally adds the addedByPlugin field to selected collections.
• defaultDateRangeDays: fallback date range when dashboard query params are absent.
• hyrosApiKeyEnvVarName: custom environment variable name used to read the Hyros API key.
• widgetStyle: controls the widget theme. Supported values are default and minimal.
• disabled: disables runtime plugin behavior while preserving schema changes.

Widget Themes

This plugin supports multiple widget themes through the widgetStyle option.

Theme behavior:

• default: Payload-like card styling with neutral background, border, and no extra gradients.
• minimal: lighter/transparent look that keeps a visible border.

If you do not set widgetStyle, the plugin uses default.

Theme Configuration Examples

Use default theme explicitly:

import { buildConfig } from 'payload'
import { payloadPluginHyrosWidget } from '@main12/payload-hyros-widget'

export default buildConfig({
  plugins: [
    payloadPluginHyrosWidget({
      widgetStyle: 'default',
    }),
  ],
})

Use minimal theme:

import { buildConfig } from 'payload'
import { payloadPluginHyrosWidget } from '@main12/payload-hyros-widget'

export default buildConfig({
  plugins: [
    payloadPluginHyrosWidget({
      widgetStyle: 'minimal',
    }),
  ],
})

Combined configuration example:

import { buildConfig } from 'payload'
import { payloadPluginHyrosWidget } from '@main12/payload-hyros-widget'

export default buildConfig({
  plugins: [
    payloadPluginHyrosWidget({
      widgetStyle: 'default',
      defaultDateRangeDays: 30,
      hyrosApiKeyEnvVarName: 'HYROS_API_KEY',
    }),
  ],
})

Dashboard Setup

This plugin registers real Payload dashboard widgets through config.admin.dashboard.widgets and also seeds a default dashboard layout so the widgets can be rearranged in the Payload dashboard editor.

Registered widgets:

• Hyros Total Revenue
• Hyros Qualified Sales
• Hyros Refunds & Discounts
• Hyros Revenue Trend
• Hyros Product Mix
• Hyros Total Leads
• Hyros Leads Trend
• Hyros Lead Funnel
• Hyros Top Tags

API Endpoint

The plugin registers the Payload endpoint:

• GET /api/{apiRoute}/hyros/dashboard

Query params:

• fromDate (optional, ISO day)
• toDate (optional, ISO day)

If omitted, the plugin uses defaultDateRangeDays ending at today.

Architecture

The implementation follows a clean architecture orientation:

• Interface layer:
  • src/endpoints/hyrosDashboardHandler.ts
  • src/widgets/HyrosMetricWidget/Component.client.tsx
  • src/widgets/*Widget/Component.client.tsx
• Domain layer:
  • src/hyros/analytics.ts
• Infrastructure layer:
  • src/hyros/client.ts
  • src/hyros/types.ts
  • src/hyros/options.ts

Widget registration:

• src/widgets/index.ts
• src/widgets/useHyrosDashboardData.ts
• src/widgets/HyrosWidget.module.css

This keeps business rules independent from transport and UI details.

Development

pnpm install
pnpm dev

Useful scripts:

• pnpm lint
• pnpm test:int
• pnpm test:e2e
• pnpm build

Notes

• The Hyros API key is never exposed in browser requests.
• Dashboard widgets fetch from the Payload endpoint, not directly from Hyros.