Skip to content

A modern and easy to use dashboard. 80+ integrations. 20K+ icons built in. Authentication out of the box. No YAML, drag and drop configuration.

7.3 KB
Raw Blame
import { exportCustomWidgetDefinition } from "@homarr/custom-widgets/core";
import { assertCustomWidgetIntegrationBindings } from "./source-resolver";
import { TRPCError } from "@trpc/server";
import { z } from "zod/v4";

import {
  applyCustomWidgetSourceSetup,
  CUSTOM_WIDGET_SCHEMA,
  customWidgetDefinitionSchema,
  customWidgetIdentifierSchema,
  customWidgetSecretsInputSchema,
  getCustomWidgetSecretRequirements,
  getCustomWidgetSourceSetups,
} from "@homarr/custom-widgets/core";
import { createLogger } from "@homarr/core/infrastructure/logs";
import { WorkshopBackend } from "@homarr/workshop/backend";
import { resolveHomarrUrlConfig, validateWorkshopWidget } from "@homarr/workshop/schema";

import { env } from "../../env";
import { permissionRequiredProcedure } from "../../trpc";
import { insertCustomWidgetDefinition } from "./definition-insert";
import { assertSecretSources } from "./secret-policy";

const logger = createLogger({ module: "custom-widget:workshop" });
const workshopUrls = resolveHomarrUrlConfig({
  homarrWebsiteUrl: env.HOMARR_WEBSITE_URL,
  workshopApiUrl: env.WORKSHOP_API_URL,
  workshopWebUrl: env.WORKSHOP_WEB_URL,
});
const workshop = new WorkshopBackend(workshopUrls.workshopApiUrl);
const getWorkshopSubmissionUrl = (submissionId: string) =>
  `${workshopUrls.workshopWebUrl}/${encodeURIComponent(submissionId)}`;

function throwWorkshopUnavailable(
  message: string,
  event: "workshop_widget_lookup_failed" | "workshop_widget_search_failed",
): never {
  logger.error(message, {
    event,
    errorName: "WorkshopBackendError",
  });
  throw new TRPCError({
    code: "BAD_GATEWAY",
    message: "Workshop is unavailable",
  });
}

async function getWorkshopWidget(submissionId: string) {
  try {
    const submission = await workshop.get(submissionId);
    if (submission.type !== "customWidget" || submission.widgetSchema !== CUSTOM_WIDGET_SCHEMA) {
      throw new TRPCError({
        code: "BAD_REQUEST",
        message: "Workshop submission is not a compatible Custom JSX widget",
      });
    }
    const validation = validateWorkshopWidget(submission.content);
    if (!validation.success) {
      throw new TRPCError({ code: "BAD_REQUEST", message: validation.error });
    }
    return { submission, widget: exportCustomWidgetDefinition(validation.data) };
  } catch (error) {
    if (error instanceof TRPCError) throw error;
    throwWorkshopUnavailable("Workshop widget lookup failed", "workshop_widget_lookup_failed");
  }
}

const workshopSearchInputSchema = z.object({
  query: z.string().trim().min(1).max(200),
  sort: z.enum(["top", "newest", "recent", "discussed"]).default("top"),
  limit: z.number().int().min(1).max(20).default(10),
});

const sourceOverridesSchema = z.record(
  customWidgetIdentifierSchema,
  z.strictObject({
    baseUrl: z.string().optional(),
    networkScope: z.unknown().optional(),
    integrationId: z.string().min(1).max(100).optional(),
  }),
);

export const workshopProcedures = {
  workshopSearch: permissionRequiredProcedure
    .requiresPermission("admin")
    .meta({ mcp: { enabled: true, description: "Search Workshop for Custom JSX widgets." } })
    .input(workshopSearchInputSchema)
    .query(async ({ input }) => {
      try {
        const result = await workshop.list({
          page: 1,
          perPage: input.limit,
          search: input.query,
          sort: input.sort,
          type: "customWidget",
          includeOutdated: true,
        });
        return {
          items: result.items
            .filter((item) => item.widgetSchema === CUSTOM_WIDGET_SCHEMA)
            .map((item) => ({
              id: item.id,
              url: getWorkshopSubmissionUrl(item.id),
              title: item.title,
              description: item.description,
              authorName: item.authorName,
              score: item.score,
              revision: item.revision,
              outdated: item.outdated,
              reportCount: item.reportCount,
            })),
        };
      } catch {
        throwWorkshopUnavailable("Workshop widget search failed", "workshop_widget_search_failed");
      }
    }),

  workshopGet: permissionRequiredProcedure
    .requiresPermission("admin")
    .meta({ mcp: { enabled: true, description: "Get and validate one Workshop Custom JSX widget." } })
    .input(z.object({ submissionId: z.string().min(1) }))
    .query(async ({ input }) => {
      const { submission, widget } = await getWorkshopWidget(input.submissionId);
      return {
        submission: {
          id: submission.id,
          url: getWorkshopSubmissionUrl(submission.id),
          title: submission.title,
          description: submission.description,
          authorName: submission.authorName,
          revision: submission.revision,
          score: submission.score,
          outdated: submission.outdated,
          reportCount: submission.reportCount,
        },
        widget,
        sourceSetup: getCustomWidgetSourceSetups(widget.sources),
        hasActions: Object.values(widget.requests).some((request) => request.kind === "action"),
        methods: [...new Set(Object.values(widget.requests).map((request) => request.method))],
        permissions: [...new Set(Object.values(widget.requests).map((request) => request.permission))],
      };
    }),

  workshopInstall: permissionRequiredProcedure
    .requiresPermission("admin")
    .meta({
      mcp: { enabled: true, effect: "additive", description: "Install one validated Workshop Custom JSX widget." },
    })
    .input(
      z.object({
        submissionId: z.string().min(1),
        name: z.string().trim().min(1).max(128).optional(),
        sources: sourceOverridesSchema.default({}),
        secrets: customWidgetSecretsInputSchema.default([]),
      }),
    )
    .mutation(async ({ ctx, input }) => {
      const { widget } = await getWorkshopWidget(input.submissionId);
      const unknownSource = Object.keys(input.sources).find((sourceId) => !widget.sources[sourceId]);
      if (unknownSource) {
        throw new TRPCError({ code: "BAD_REQUEST", message: `Unknown Workshop widget source '${unknownSource}'` });
      }
      const configured = customWidgetDefinitionSchema.parse({
        ...widget,
        name: input.name ?? widget.name,
        sources: applyCustomWidgetSourceSetup(
          widget.sources,
          Object.fromEntries(
            Object.entries(input.sources).map(([sourceId, source]) => [
              sourceId,
              {
                baseUrl: source.baseUrl,
                integrationId: source.integrationId,
              },
            ]),
          ),
        ),
      });
      await assertCustomWidgetIntegrationBindings(ctx, configured.sources);
      assertSecretSources(configured.sources, input.secrets);
      const id = await insertCustomWidgetDefinition(ctx.db, configured, ctx.session.user.id, input.secrets);
      const configuredSecrets = new Set(input.secrets.map((secret) => `${secret.sourceId}:${secret.kind}`));
      return {
        status: "installed" as const,
        definitionId: id,
        sourceSetup: getCustomWidgetSourceSetups(configured.sources, input.secrets),
        missingCredentials: getCustomWidgetSecretRequirements(configured.sources)
          .filter((requirement) => !configuredSecrets.has(`${requirement.sourceId}:${requirement.kind}`))
          .map(({ sourceId, kind }) => ({ sourceId, kind })),
      };
    }),
};