@nimee/wallet-generator 1.0.0

package/src/apple/ApplePassGenerator.ts

@@ -0,0 +1,291 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { Worker } from 'worker_threads';
+import * as imageHelpers from '../helpers/imageHelpers';
+import { IWalletPassData, IAppleWalletConfig, IWalletLayoutField } from '../types';
+
+// ─── Apple pass image dimensions ─────────────────────────────────────────────
+
+const LOGO_1X = { w: 160, h: 50 };
+const LOGO_2X = { w: 320, h: 100 };
+const ICON_1X = { w: 29, h: 29 };
+const ICON_2X = { w: 58, h: 58 };
+const STRIP_1X = { w: 375, h: 123 };
+const STRIP_2X = { w: 750, h: 246 };
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface ApplePassGeneratorOptions {
+  /** Allowed image host list passed to downloadImageBuffer. Empty = all https hosts. */
+  allowedHosts?: string[];
+  /** Worker thread timeout in milliseconds. Defaults to 15 000. */
+  workerTimeoutMs?: number;
+}
+
+interface PassImage {
+  name: string;
+  buffer: Buffer;
+}
+
+interface WorkerPayload {
+  modelPath: string;
+  certificates: { signerCert: string; signerKey: string; wwdr: string };
+  passOverrides: Record<string, unknown>;
+  images: PassImage[];
+  barcodes: { message: string; format: string; messageEncoding: string };
+  layoutFields: Array<{ key: string; label: string; value: string; row: string }>;
+  relevantDate: string;
+}
+
+// ─── Field resolver ───────────────────────────────────────────────────────────
+
+/**
+ * Maps a layout field key to a label/value pair derived from pass data.
+ * Keys are the same ones used in the user-event WalletService.
+ */
+function resolveField(
+  key: string,
+  data: IWalletPassData
+): { label: string; value: string } | undefined {
+  switch (key) {
+    case 'event':
+    case 'passTitle':
+      return data.passTitle ? { label: 'Event', value: data.passTitle } : undefined;
+    case 'holder':
+    case 'holderName':
+    case 'attendee':
+      return data.holderName ? { label: 'Name', value: data.holderName } : undefined;
+    case 'date':
+    case 'dateDisplay':
+      return data.dateDisplay ? { label: 'Date', value: data.dateDisplay } : undefined;
+    case 'seat':
+      return data.seat ? { label: 'Seat', value: data.seat } : undefined;
+    case 'order':
+    case 'orderNumber':
+      return data.orderNumber ? { label: 'Order', value: data.orderNumber } : undefined;
+    case 'subtitle':
+    case 'passSubtitle':
+      return data.passSubtitle ? { label: 'Ticket', value: data.passSubtitle } : undefined;
+    case 'plan_name':
+      return data.passTitle ? { label: 'Plan', value: data.passTitle } : undefined;
+    case 'member_name':
+      return data.holderName ? { label: 'Member', value: data.holderName } : undefined;
+    case 'valid_from': {
+      const value = data.dateDisplay || (data.startDate ? data.startDate.toLocaleDateString('he-IL') : '') || '';
+      return value ? { label: 'Valid From', value } : undefined;
+    }
+    case 'valid_to': {
+      const value = data.endDate ? data.endDate.toLocaleDateString('he-IL') : '';
+      return value ? { label: 'Valid To', value } : undefined;
+    }
+    default:
+      return undefined;
+  }
+}
+
+// ─── ApplePassGenerator ───────────────────────────────────────────────────────
+
+export class ApplePassGenerator {
+  private readonly allowedHosts: string[];
+  private readonly workerTimeoutMs: number;
+
+  constructor(options: ApplePassGeneratorOptions = {}) {
+    this.allowedHosts = options.allowedHosts ?? [];
+    this.workerTimeoutMs = options.workerTimeoutMs ?? 15_000;
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  /**
+   * Generates a signed Apple Wallet pass buffer.
+   *
+   * @param data       - Caller-assembled pass data (all DB resolution done upstream).
+   * @param config     - Apple certificates and identifiers.
+   * @param defaultLayout - Layout fields to use when data.layout is absent.
+   * @returns Signed `.pkpass` buffer ready to stream to the client.
+   */
+  async generate(
+    data: IWalletPassData,
+    config: IAppleWalletConfig,
+    defaultLayout: IWalletLayoutField[]
+  ): Promise<Buffer> {
+    const images = await this.prepareImages(data);
+    const layoutFields = this.resolveLayout(data, defaultLayout);
+    const modelPath = this.resolveTemplatePath(config);
+
+    const passOverrides: Record<string, unknown> = {
+      passTypeIdentifier: config.passTypeIdentifier,
+      teamIdentifier: config.teamIdentifier,
+      serialNumber: data.objectId,
+      description: data.passTitle,
+      organizationName: data.marketplaceName ?? 'Nimi',
+      logoText: data.marketplaceName ?? 'Nimi',
+      ...(data.backgroundColor && { backgroundColor: data.backgroundColor }),
+      ...(data.foregroundColor && { foregroundColor: data.foregroundColor }),
+      ...(data.labelColor && { labelColor: data.labelColor }),
+      ...(data.isCheckedIn && { voided: true }),
+    };
+
+    const workerPayload: WorkerPayload = {
+      modelPath,
+      certificates: {
+        signerCert: config.cert,
+        signerKey: config.key,
+        wwdr: config.wwdr,
+      },
+      passOverrides,
+      images,
+      barcodes: {
+        message: data.qrContent,
+        format: 'PKBarcodeFormatQR',
+        messageEncoding: 'iso-8859-1',
+      },
+      layoutFields,
+      relevantDate: (data.startDate ?? new Date()).toISOString(),
+    };
+
+    return this.spawnWorker(workerPayload);
+  }
+
+  // ── Template path resolution ───────────────────────────────────────────────
+
+  /**
+   * Returns the absolute path to the `.pass` template directory.
+   * Uses `config.templatePath` when provided; otherwise falls back to the
+   * bundled template shipped with the library.
+   */
+  resolveTemplatePath(config: IAppleWalletConfig): string {
+    return config.templatePath ?? path.join(__dirname, "template.pass");
+  }
+
+  // ── Worker spawn ───────────────────────────────────────────────────────────
+
+  /**
+   * Spawns the `signPassWorker` in a worker thread and returns the signed buffer.
+   * Automatically selects the compiled `.js` file in production and falls back to
+   * the `.ts` source in development (when ts-node is available).
+   */
+  spawnWorker(workerData: WorkerPayload): Promise<Buffer> {
+    const jsPath = path.resolve(__dirname, 'signPassWorker.js');
+    const tsPath = path.resolve(__dirname, 'signPassWorker.ts');
+    const workerPath = require('fs').existsSync(jsPath) ? jsPath : tsPath;
+
+    const { workerTimeoutMs } = this;
+
+    return new Promise<Buffer>((resolve, reject) => {
+      const isTs = workerPath.endsWith('.ts');
+      const worker = new Worker(workerPath, {
+        ...(isTs && { execArgv: ['--require', 'ts-node/register'] }),
+        workerData,
+      });
+
+      const cleanup = () => {
+        clearTimeout(timer);
+        worker.removeAllListeners();
+      };
+
+      const timer = setTimeout(() => {
+        cleanup();
+        worker.terminate();
+        reject(new Error(`[ApplePassGenerator] worker timed out after ${workerTimeoutMs}ms`));
+      }, workerTimeoutMs);
+
+      worker.on('message', (msg) => {
+        cleanup();
+        if (msg?.error) {
+          reject(new Error(msg.error));
+        } else {
+          resolve(Buffer.from(msg));
+        }
+      });
+
+      worker.on('error', (err) => {
+        cleanup();
+        reject(err);
+      });
+
+      worker.on('exit', (code) => {
+        cleanup();
+        if (code !== 0) {
+          reject(new Error(`[ApplePassGenerator] worker exited with code ${code}`));
+        }
+      });
+    });
+  }
+
+  // ── Private helpers ────────────────────────────────────────────────────────
+
+  /**
+   * Downloads logo and strip images in parallel, resizes them to Apple specs,
+   * and returns a flat list of named buffers ready to pass to the worker.
+   */
+  private async prepareImages(data: IWalletPassData): Promise<PassImage[]> {
+    const imageTimeoutMs = 5_000;
+    const [rawLogo, rawStrip] = await Promise.all([
+      data.logoUrl
+        ? imageHelpers.downloadImageBuffer(data.logoUrl, this.allowedHosts, imageTimeoutMs)
+        : Promise.resolve(undefined),
+      data.stripImageUrl
+        ? imageHelpers.downloadImageBuffer(data.stripImageUrl, this.allowedHosts, imageTimeoutMs)
+        : Promise.resolve(undefined),
+    ]);
+
+    // Fall back to bundled template icon when logo download fails or URL absent
+    let logoBuffer: Buffer | undefined = rawLogo;
+    if (!logoBuffer) {
+      const templateIcon = path.join(__dirname, 'template.pass', 'icon.png');
+      try {
+        logoBuffer = await fs.promises.readFile(templateIcon);
+      } catch {
+        // No fallback available — pass will use whatever is baked into the template
+      }
+    }
+
+    const images: PassImage[] = [];
+
+    if (logoBuffer) {
+      const [logo1x, logo2x, icon1x, icon2x] = await Promise.all([
+        imageHelpers.resizeImageBuffer(logoBuffer, LOGO_1X.w, LOGO_1X.h),
+        imageHelpers.resizeImageBuffer(logoBuffer, LOGO_2X.w, LOGO_2X.h),
+        imageHelpers.resizeImageBuffer(logoBuffer, ICON_1X.w, ICON_1X.h),
+        imageHelpers.resizeImageBuffer(logoBuffer, ICON_2X.w, ICON_2X.h),
+      ]);
+      if (logo1x) images.push({ name: 'logo.png', buffer: logo1x });
+      if (logo2x) images.push({ name: 'logo@2x.png', buffer: logo2x });
+      if (icon1x) images.push({ name: 'icon.png', buffer: icon1x });
+      if (icon2x) images.push({ name: 'icon@2x.png', buffer: icon2x });
+    }
+
+    if (rawStrip) {
+      const [strip1x, strip2x] = await Promise.all([
+        imageHelpers.resizeImageBuffer(rawStrip, STRIP_1X.w, STRIP_1X.h),
+        imageHelpers.resizeImageBuffer(rawStrip, STRIP_2X.w, STRIP_2X.h),
+      ]);
+      if (strip1x) images.push({ name: 'strip.png', buffer: strip1x });
+      if (strip2x) images.push({ name: 'strip@2x.png', buffer: strip2x });
+    }
+
+    return images;
+  }
+
+  /**
+   * Resolves layout fields from pass data (or falls back to `defaultLayout`),
+   * filters out hidden rows, and maps each field key to a label/value pair.
+   */
+  private resolveLayout(
+    data: IWalletPassData,
+    defaultLayout: IWalletLayoutField[]
+  ): Array<{ key: string; label: string; value: string; row: string }> {
+    const fields = (data.layout?.fields ?? defaultLayout)
+      .filter((f) => f.row !== 'hidden')
+      .sort((a, b) => a.position - b.position);
+
+    const result: Array<{ key: string; label: string; value: string; row: string }> = [];
+    for (const f of fields) {
+      const resolved = resolveField(f.key, data);
+      if (!resolved) continue;
+      result.push({ key: f.key, label: resolved.label, value: resolved.value, row: f.row });
+    }
+    return result;
+  }
+}

package/src/apple/signPassWorker.ts

@@ -0,0 +1,52 @@
+import { parentPort, workerData } from "worker_threads";
+import { PKPass } from "passkit-generator";
+
+interface PassImage {
+  name: string;
+  buffer: Buffer;
+}
+
+interface WorkerData {
+  modelPath: string;
+  certificates: { signerCert: string; signerKey: string; wwdr: string };
+  passOverrides: Record<string, any>;
+  images: PassImage[];
+  barcodes: { message: string; format: string; messageEncoding: string };
+  layoutFields: Array<{ key: string; label: string; value: string; row: string }>;
+  relevantDate: string;
+}
+
+async function run() {
+  const data = workerData as WorkerData;
+
+  const pass = await PKPass.from(
+    {
+      model: data.modelPath,
+      certificates: data.certificates,
+    },
+    data.passOverrides
+  );
+
+  pass.setRelevantDate(new Date(data.relevantDate));
+
+  for (const img of data.images) {
+    pass.addBuffer(img.name, Buffer.from(img.buffer));
+  }
+
+  pass.setBarcodes(data.barcodes as any);
+
+  for (const f of data.layoutFields) {
+    const entry = { key: f.key, label: f.label, value: f.value };
+    if (f.row === "header") pass.headerFields.push(entry);
+    if (f.row === "secondary") pass.secondaryFields.push(entry);
+    if (f.row === "auxiliary") pass.auxiliaryFields.push(entry);
+    if (f.row === "back") pass.backFields.push(entry);
+  }
+
+  const buffer = pass.getAsBuffer();
+  parentPort!.postMessage(buffer);
+}
+
+run().catch((err) => {
+  parentPort!.postMessage({ error: err.message || String(err) });
+});

package/src/apple/template.pass/pass.json

@@ -0,0 +1,16 @@
+{
+  "formatVersion": 1,
+  "passTypeIdentifier": "pass.il.co.nimi.event-ticket",
+  "teamIdentifier": "PLACEHOLDER",
+  "organizationName": "PLACEHOLDER",
+  "description": "Event Ticket",
+  "foregroundColor": "rgb(255, 255, 255)",
+  "backgroundColor": "rgb(60, 65, 76)",
+  "labelColor": "rgb(200, 200, 200)",
+  "eventTicket": {
+    "primaryFields": [],
+    "secondaryFields": [],
+    "auxiliaryFields": [],
+    "backFields": []
+  }
+}

package/src/google/GooglePassGenerator.ts

@@ -0,0 +1,104 @@
+import axios from 'axios';
+import jwt from 'jsonwebtoken';
+import logger from '@nimee/logger';
+import { IGoogleWalletConfig, IWalletPassData } from '../types';
+import { ensureGoogleTicketClass, getGoogleAccessToken, buildGoogleTicketObject } from './googleAuth';
+
+export class GooglePassGenerator {
+  /**
+   * Builds the full Google Wallet class ID.
+   * Uses config.classId if provided; otherwise derives from issuerId + data.classIdSuffix.
+   */
+  private buildClassId(data: IWalletPassData, config: IGoogleWalletConfig): string {
+    if (config.classId) {
+      return config.classId;
+    }
+    const suffix = data.classIdSuffix || data.objectId;
+    return `${config.issuerId}.${suffix}`;
+  }
+
+  /**
+   * Ensures the Google Wallet EventTicketClass exists (creates or patches).
+   * Delegates to the shared googleAuth helper.
+   */
+  private async ensureClass(classId: string, data: IWalletPassData, config: IGoogleWalletConfig): Promise<void> {
+    // Pass a config override with the resolved classId so ensureGoogleTicketClass
+    // uses exactly the classId we computed instead of recomputing it.
+    const configWithClass: IGoogleWalletConfig = { ...config, classId };
+    await ensureGoogleTicketClass(configWithClass, data);
+  }
+
+  /**
+   * Builds the Google Wallet ticket object payload.
+   * Delegates to the shared builder in googleAuth.
+   */
+  private buildObject(objectId: string, classId: string, data: IWalletPassData): object {
+    return buildGoogleTicketObject(objectId, classId, data);
+  }
+
+  /**
+   * Signs the JWT payload with the service account private key using RS256.
+   */
+  private signJwt(ticketObject: object, config: IGoogleWalletConfig): string {
+    const claims = {
+      iss: config.serviceAccountEmail,
+      aud: 'google',
+      origins: [] as string[],
+      typ: 'savetowallet',
+      payload: {
+        eventTicketObjects: [ticketObject],
+      },
+    };
+
+    return jwt.sign(claims, config.privateKey, { algorithm: 'RS256' });
+  }
+
+  /**
+   * Generates a Google Wallet "Add to Wallet" save URL for the given pass data.
+   */
+  async generateSaveUrl(data: IWalletPassData, config: IGoogleWalletConfig): Promise<string> {
+    const classId = this.buildClassId(data, config);
+
+    await this.ensureClass(classId, data, config);
+
+    const objectId = `${config.issuerId}.${data.objectId}`.replace(/[^a-zA-Z0-9_.\-]/g, '-');
+    const ticketObject = this.buildObject(objectId, classId, data);
+    const token = this.signJwt(ticketObject, config);
+
+    logger.info(`[GooglePassGenerator] save URL generated for objectId=${data.objectId}`);
+    return `https://pay.google.com/gp/v/save/${token}`;
+  }
+
+  /**
+   * PATCHes the Google Wallet object state (ACTIVE | EXPIRED | INACTIVE).
+   * Never throws — swallows all errors and logs a warning instead.
+   */
+  async updateObjectState(
+    rawObjectId: string,
+    config: IGoogleWalletConfig,
+    state: 'ACTIVE' | 'EXPIRED' | 'INACTIVE'
+  ): Promise<void> {
+    try {
+      const accessToken = await getGoogleAccessToken(config);
+      const encodedId = encodeURIComponent(rawObjectId);
+      const url = `https://walletobjects.googleapis.com/walletobjects/v1/eventTicketObject/${encodedId}`;
+
+      await axios.patch(
+        url,
+        { state },
+        {
+          headers: { Authorization: `Bearer ${accessToken}` },
+          timeout: 5000,
+        }
+      );
+
+      logger.info(`[GooglePassGenerator] object ${rawObjectId} state updated to ${state}`);
+    } catch (err) {
+      logger.warn(
+        `[GooglePassGenerator] failed to update object state for ${rawObjectId} → ${state}: ${
+          err instanceof Error ? err.message : String(err)
+        }`
+      );
+    }
+  }
+}

package/src/google/googleAuth.ts

@@ -0,0 +1,134 @@
+import axios from "axios";
+import jwt from "jsonwebtoken";
+import logger from "@nimee/logger";
+import { IGoogleWalletConfig, IWalletPassData } from "../types";
+
+// ─── Token cache ──────────────────────────────────────────────────────────────
+
+interface IGoogleTokenCache {
+  accessToken: string;
+  expiresAt: number; // epoch ms
+}
+
+// Intentional module-level singletons — shared across all Wallet instances
+// (each pod maintains its own in-memory cache).
+const googleTokenCache = new Map<string, IGoogleTokenCache>();
+const googleClassSyncedAt = new Map<string, number>(); // classId → epoch ms
+const CLASS_SYNC_TTL_MS = 60 * 60 * 1000; // re-sync class at most once per hour
+
+// ─── OAuth ────────────────────────────────────────────────────────────────────
+
+/** Exchanges service account credentials for a Google OAuth2 access token (cached for ~1 hour). */
+export async function getGoogleAccessToken(config: IGoogleWalletConfig): Promise<string> {
+  const cached = googleTokenCache.get(config.serviceAccountEmail);
+  if (cached && cached.expiresAt - Date.now() > 5 * 60 * 1000) {
+    return cached.accessToken;
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const assertion = jwt.sign(
+    {
+      iss: config.serviceAccountEmail,
+      sub: config.serviceAccountEmail,
+      aud: "https://oauth2.googleapis.com/token",
+      scope: "https://www.googleapis.com/auth/wallet_object.issuer",
+      iat: now,
+      exp: now + 3600,
+    },
+    config.privateKey,
+    { algorithm: "RS256" }
+  );
+
+  const response = await axios.post(
+    "https://oauth2.googleapis.com/token",
+    new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion }),
+    { headers: { "Content-Type": "application/x-www-form-urlencoded" }, timeout: 5000 }
+  );
+
+  const accessToken: string = response.data.access_token;
+  googleTokenCache.set(config.serviceAccountEmail, { accessToken, expiresAt: Date.now() + 3600 * 1000 });
+  return accessToken;
+}
+
+// ─── Class sync ───────────────────────────────────────────────────────────────
+
+/**
+ * Ensures the Google Wallet EventTicketClass exists and is up to date.
+ * Skipped if successfully synced within the last hour.
+ * Attempts to create; if it already exists (409), patches instead.
+ */
+export async function ensureGoogleTicketClass(config: IGoogleWalletConfig, data: IWalletPassData): Promise<void> {
+  const classId = config.classId || `${config.issuerId}.event-${data.classIdSuffix || data.objectId}`;
+
+  if (Date.now() - (googleClassSyncedAt.get(classId) ?? 0) < CLASS_SYNC_TTL_MS) {
+    return;
+  }
+
+  const accessToken = await getGoogleAccessToken(config);
+  const classBody = buildGoogleTicketClass(classId, data);
+  const baseUrl = "https://walletobjects.googleapis.com/walletobjects/v1/eventTicketClass";
+  const headers = { Authorization: `Bearer ${accessToken}` };
+
+  try {
+    await axios.post(baseUrl, classBody, { headers, timeout: 5000 });
+    googleClassSyncedAt.set(classId, Date.now());
+  } catch (err: any) {
+    if (err.response?.status === 409) {
+      await axios.patch(`${baseUrl}/${encodeURIComponent(classId)}`, classBody, { headers, timeout: 5000 });
+      googleClassSyncedAt.set(classId, Date.now());
+    } else {
+      throw new Error(`failed to sync Google Wallet class: ${err.response?.data?.error?.message ?? err.message}`);
+    }
+  }
+}
+
+// ─── Object / class builders ──────────────────────────────────────────────────
+
+export function buildGoogleTicketObject(objectId: string, classId: string, data: IWalletPassData): object {
+  const dateDisplay = data.dateDisplay;
+
+  return {
+    id: objectId,
+    classId,
+    state: data.isCheckedIn ? "COMPLETED" : "ACTIVE",
+    ticketHolderName: data.holderName,
+    issueName: data.marketplaceName || "",
+    ticketNumber: data.orderNumber || "",
+    ...(data.logoUrl && { logo: { sourceUri: { uri: data.logoUrl } } }),
+    barcode: {
+      type: "QR_CODE",
+      value: data.qrContent,
+      ...(data.orderNumber && { alternateText: data.orderNumber }),
+    },
+    eventName: {
+      defaultValue: { language: "en-US", value: data.passTitle || "" },
+    },
+    ...(data.backgroundColorHex && { hexBackgroundColor: data.backgroundColorHex }),
+    ...((data.seat) && {
+      seatInfo: {
+        ...(data.seat && { seat: { defaultValue: { language: "en-US", value: data.seat } } }),
+      },
+    }),
+    textModulesData: [
+      { header: "TICKET", body: data.passSubtitle || data.passTitle || "" },
+      ...(dateDisplay ? [{ header: "DATE", body: dateDisplay }] : []),
+    ],
+    validTimeInterval: {
+      start: { date: (data.startDate || new Date()).toISOString() },
+      ...(data.endDate && { end: { date: data.endDate.toISOString() } }),
+    },
+  };
+}
+
+export function buildGoogleTicketClass(classId: string, data: IWalletPassData): object {
+  return {
+    id: classId,
+    issuerName: data.marketplaceName || "",
+    reviewStatus: "UNDER_REVIEW",
+    eventName: {
+      defaultValue: { language: "en-US", value: data.passTitle || "" },
+    },
+    ...(data.logoUrl && { logo: { sourceUri: { uri: data.logoUrl } } }),
+    ...(data.stripImageUrl && { heroImage: { sourceUri: { uri: data.stripImageUrl } } }),
+  };
+}

package/src/helpers/colorHelpers.ts

@@ -0,0 +1,34 @@
+// ─── Color normalization ──────────────────────────────────────────────────────
+
+export interface INormalizedColor {
+  rgb: string;
+  hex: string;
+}
+
+/**
+ * Normalizes "#3c4150", "3c4150", or "rgb(60, 65, 80)" to both Apple rgb() and hex formats.
+ * Returns undefined if the input is missing or invalid.
+ */
+export function normalizeColor(raw: string): INormalizedColor | undefined {
+  if (!raw || !raw.trim()) return undefined;
+
+  const rgbMatch = raw.match(/^rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$/);
+  if (rgbMatch) {
+    const r = parseInt(rgbMatch[1]);
+    const g = parseInt(rgbMatch[2]);
+    const b = parseInt(rgbMatch[3]);
+    if (r > 255 || g > 255 || b > 255) return undefined;
+    const hex = `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
+    return { rgb: `rgb(${r},${g},${b})`, hex };
+  }
+
+  const cleaned = raw.replace('#', '');
+  if (/^[0-9a-fA-F]{6}$/.test(cleaned)) {
+    const r = parseInt(cleaned.slice(0, 2), 16);
+    const g = parseInt(cleaned.slice(2, 4), 16);
+    const b = parseInt(cleaned.slice(4, 6), 16);
+    return { rgb: `rgb(${r},${g},${b})`, hex: `#${cleaned.toLowerCase()}` };
+  }
+
+  return undefined;
+}