@nimee/wallet-generator 1.0.0

package/src/helpers/imageHelpers.ts

@@ -0,0 +1,87 @@
+import axios from 'axios';
+import sharp from 'sharp';
+
+// ─── Image validation constants ───────────────────────────────────────────────
+
+export const IMAGE_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
+export const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+export const JPEG_MAGIC = Buffer.from([0xff, 0xd8, 0xff]);
+export const WEBP_RIFF = Buffer.from([0x52, 0x49, 0x46, 0x46]);
+export const WEBP_WEBP = Buffer.from([0x57, 0x45, 0x42, 0x50]);
+
+// ─── URL validation ───────────────────────────────────────────────────────────
+
+/**
+ * Returns true if the URL is safe to fetch for wallet images.
+ * Requires https:// and optionally restricts to hosts in the allowedHosts list.
+ * An empty allowedHosts list means all https hosts are permitted.
+ */
+export function isAllowedImageUrl(url: string, allowedHosts: string[]): boolean {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== 'https:') return false;
+
+  if (allowedHosts.length === 0) return true;
+
+  return allowedHosts.some((host) => parsed.hostname === host || parsed.hostname.endsWith(`.${host}`));
+}
+
+// ─── Image download ───────────────────────────────────────────────────────────
+
+/**
+ * Downloads an image from a URL, validates it, and returns its buffer.
+ * Returns undefined if the URL is not allowed, the download fails, or the
+ * image is invalid/too large.
+ */
+export async function downloadImageBuffer(
+  url: string,
+  allowedHosts: string[],
+  timeoutMs: number = 10_000
+): Promise<Buffer | undefined> {
+  if (!isAllowedImageUrl(url, allowedHosts)) return undefined;
+
+  try {
+    const response = await axios.get<Buffer>(url, {
+      responseType: 'arraybuffer',
+      timeout: timeoutMs,
+      maxContentLength: IMAGE_MAX_SIZE,
+    });
+
+    const buffer = Buffer.from(response.data);
+    if (buffer.length > IMAGE_MAX_SIZE) return undefined;
+
+    // Validate image format via magic bytes
+    const isPng = buffer.slice(0, 8).equals(PNG_MAGIC);
+    const isJpeg = buffer.slice(0, 3).equals(JPEG_MAGIC);
+    const isWebp =
+      buffer.slice(0, 4).equals(WEBP_RIFF) && buffer.slice(8, 12).equals(WEBP_WEBP);
+
+    if (!isPng && !isJpeg && !isWebp) return undefined;
+
+    return buffer;
+  } catch {
+    return undefined;
+  }
+}
+
+// ─── Image resize helper ──────────────────────────────────────────────────────
+
+/**
+ * Resizes an image buffer to the given dimensions using sharp.
+ * Returns undefined on error.
+ */
+export async function resizeImageBuffer(
+  buffer: Buffer,
+  width: number,
+  height: number
+): Promise<Buffer | undefined> {
+  try {
+    return await sharp(buffer).resize(width, height, { fit: 'inside' }).png().toBuffer();
+  } catch {
+    return undefined;
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './helpers/colorHelpers';
+export * from './helpers/imageHelpers';
+export { ApplePassGenerator } from './apple/ApplePassGenerator';
+export { GooglePassGenerator } from './google/GooglePassGenerator';

package/src/types.ts

@@ -0,0 +1,66 @@
+export interface IWalletLayoutField {
+  key: string;
+  row: 'header' | 'secondary' | 'auxiliary' | 'back' | 'hidden';
+  position: number;
+}
+
+/**
+ * Caller-assembled pass data. All design values (colors, URLs) must be
+ * pre-resolved by the service before passing in — generators do not touch the DB.
+ */
+export interface IWalletPassData {
+  /** MongoDB _id of the source document (userEvent or endUserSeasonTicket). Used as Google pass object ID. */
+  objectId: string;
+  /** Person's display name shown on the pass. */
+  holderName: string;
+  /** Primary title (event name or plan name). */
+  passTitle: string;
+  /** Secondary label (ticket type, plan type). Optional. */
+  passSubtitle?: string;
+  /** Human-readable date string already formatted for display (e.g. "14/05/2026 18:00"). */
+  dateDisplay?: string;
+  startDate?: Date;
+  endDate?: Date;
+  seat?: string;
+  orderNumber?: string;
+  /** True when the QR code has already been scanned/used. Affects Google pass state. */
+  isCheckedIn?: boolean;
+  /** Raw string encoded in the QR barcode. For events: "userEventId/ticketInfoId". For subscriptions: "sub/{sellerId}/{endUserSeasonTicketId}". */
+  qrContent: string;
+  marketplaceName?: string;
+  /** Used to build the Google Wallet class ID suffix. E.g. "event-<eventId>" or "subscription". */
+  classIdSuffix?: string;
+  accountId?: string;
+  /** Pre-resolved logo URL (HTTPS). */
+  logoUrl?: string;
+  /** Pre-resolved strip/banner image URL (HTTPS). */
+  stripImageUrl?: string;
+  /** Background color in rgb() format. */
+  backgroundColor?: string;
+  /** Background color in #hex format (for Google). */
+  backgroundColorHex?: string;
+  /** Text color in rgb() format. Apple only. */
+  foregroundColor?: string;
+  /** Label color in rgb() format. Apple only. */
+  labelColor?: string;
+  /** Layout from walletDesign. Generators fall back to their own DEFAULT_LAYOUT if absent. */
+  layout?: { fields: IWalletLayoutField[] };
+}
+
+export interface IAppleWalletConfig {
+  cert: string;
+  key: string;
+  wwdr: string;
+  passTypeIdentifier: string;
+  teamIdentifier: string;
+  /** Absolute path to the `.pass` template directory. Defaults to the bundled template. */
+  templatePath?: string;
+}
+
+export interface IGoogleWalletConfig {
+  issuerId: string;
+  /** If provided, used as-is. Otherwise built from issuerId + data.classIdSuffix. */
+  classId?: string;
+  serviceAccountEmail: string;
+  privateKey: string;
+}

package/tests/apple/ApplePassGenerator.test.ts

@@ -0,0 +1,47 @@
+import sinon from 'sinon';
+import * as imageHelpers from '../../src/helpers/imageHelpers';
+import { ApplePassGenerator } from '../../src/apple/ApplePassGenerator';
+import { IWalletPassData, IAppleWalletConfig, IWalletLayoutField } from '../../src/types';
+
+const MOCK_CONFIG: IAppleWalletConfig = {
+  cert: 'cert-pem',
+  key: 'key-pem',
+  wwdr: 'wwdr-pem',
+  passTypeIdentifier: 'pass.il.co.nimi.test',
+  teamIdentifier: 'TEAMID123',
+};
+
+const MOCK_DATA: IWalletPassData = {
+  objectId: 'abc123',
+  holderName: 'John Doe',
+  passTitle: 'Summer Event',
+  qrContent: 'abc123/ticket456',
+  isCheckedIn: false,
+};
+
+const DEFAULT_LAYOUT: IWalletLayoutField[] = [
+  { key: 'event', row: 'secondary', position: 0 },
+];
+
+describe('ApplePassGenerator', () => {
+  let generator: ApplePassGenerator;
+  let downloadStub: sinon.SinonStub;
+
+  beforeEach(() => {
+    generator = new ApplePassGenerator();
+    downloadStub = sinon.stub(imageHelpers, 'downloadImageBuffer').resolves(undefined);
+  });
+
+  afterEach(() => sinon.restore());
+
+  it('skips logo download when logoUrl is absent', async () => {
+    await generator.generate(MOCK_DATA, MOCK_CONFIG, DEFAULT_LAYOUT).catch(() => {});
+    expect(downloadStub.callCount).toBe(0);
+  });
+
+  it('attempts logo download when logoUrl is present', async () => {
+    const data = { ...MOCK_DATA, logoUrl: 'https://cdn.example.com/logo.png' };
+    await generator.generate(data, MOCK_CONFIG, DEFAULT_LAYOUT).catch(() => {});
+    expect(downloadStub.calledWith('https://cdn.example.com/logo.png', sinon.match.any, sinon.match.any)).toBe(true);
+  });
+});

package/tests/google/GooglePassGenerator.test.ts

@@ -0,0 +1,47 @@
+import sinon from 'sinon';
+import { GooglePassGenerator } from '../../src/google/GooglePassGenerator';
+import { IWalletPassData, IGoogleWalletConfig } from '../../src/types';
+
+const MOCK_CONFIG: IGoogleWalletConfig = {
+  issuerId: 'issuer123',
+  classId: 'issuer123.test-class',
+  serviceAccountEmail: 'wallet@project.iam.gserviceaccount.com',
+  privateKey: '-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA0000\n-----END RSA PRIVATE KEY-----',
+};
+
+const MOCK_DATA: IWalletPassData = {
+  objectId: 'sub123',
+  holderName: 'Jane Member',
+  passTitle: 'Gold Membership',
+  qrContent: 'sub/seller456/sub123',
+  isCheckedIn: false,
+  classIdSuffix: 'account-seller456-subscription',
+};
+
+describe('GooglePassGenerator', () => {
+  let generator: GooglePassGenerator;
+
+  beforeEach(() => {
+    generator = new GooglePassGenerator();
+  });
+
+  afterEach(() => sinon.restore());
+
+  it('uses provided classId from config when present', () => {
+    const classId = (generator as any).buildClassId(MOCK_DATA, MOCK_CONFIG);
+    expect(classId).toBe('issuer123.test-class');
+  });
+
+  it('derives classId from issuerId + classIdSuffix when classId absent', () => {
+    const configWithout: IGoogleWalletConfig = { ...MOCK_CONFIG, classId: undefined };
+    const classId = (generator as any).buildClassId(MOCK_DATA, configWithout);
+    expect(classId).toBe('issuer123.account-seller456-subscription');
+  });
+
+  it('generateSaveUrl returns a Google Wallet save URL', async () => {
+    sinon.stub(generator as any, 'ensureClass').resolves();
+    sinon.stub(generator as any, 'signJwt').returns('fake-jwt-token');
+    const url = await generator.generateSaveUrl(MOCK_DATA, MOCK_CONFIG);
+    expect(url).toMatch(/^https:\/\/pay\.google\.com\/gp\/v\/save\//);
+  });
+});

package/tests/helpers/colorHelpers.test.ts

@@ -0,0 +1,30 @@
+import { normalizeColor } from '../../src/helpers/colorHelpers';
+
+describe('normalizeColor', () => {
+  it('returns undefined for empty string', () => {
+    expect(normalizeColor('')).toBeUndefined();
+  });
+
+  it('normalizes 6-digit hex to rgb and hex', () => {
+    const result = normalizeColor('#1a2b3c');
+    expect(result?.rgb).toBe('rgb(26,43,60)');
+    expect(result?.hex).toBe('#1a2b3c');
+  });
+
+  it('normalizes hex without # prefix', () => {
+    const result = normalizeColor('1a2b3c');
+    expect(result?.rgb).toBe('rgb(26,43,60)');
+    expect(result?.hex).toBe('#1a2b3c');
+  });
+
+  it('normalizes rgb() input back to both formats', () => {
+    const result = normalizeColor('rgb(26,43,60)');
+    expect(result?.rgb).toBe('rgb(26,43,60)');
+    expect(result?.hex).toBe('#1a2b3c');
+  });
+
+  it('handles rgb() with spaces', () => {
+    const result = normalizeColor('rgb(26, 43, 60)');
+    expect(result?.rgb).toBe('rgb(26,43,60)');
+  });
+});

package/tests/helpers/imageHelpers.test.ts

@@ -0,0 +1,19 @@
+import { isAllowedImageUrl } from '../../src/helpers/imageHelpers';
+
+describe('isAllowedImageUrl', () => {
+  it('accepts https URLs when no allowlist configured', () => {
+    expect(isAllowedImageUrl('https://cdn.example.com/img.png', [])).toBe(true);
+  });
+
+  it('rejects http URLs', () => {
+    expect(isAllowedImageUrl('http://cdn.example.com/img.png', [])).toBe(false);
+  });
+
+  it('rejects when host not in non-empty allowlist', () => {
+    expect(isAllowedImageUrl('https://evil.com/img.png', ['cdn.example.com'])).toBe(false);
+  });
+
+  it('accepts when host in allowlist', () => {
+    expect(isAllowedImageUrl('https://cdn.example.com/img.png', ['cdn.example.com'])).toBe(true);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+    "compileOnSave": true,
+    "compilerOptions": {
+        "module": "commonjs",
+        "esModuleInterop": true,
+        "declaration": true,
+        "target": "es6",
+        "noImplicitAny": true,
+        "skipLibCheck": true,
+        "moduleResolution": "node",
+        "sourceMap": true,
+        "outDir": "./dist",
+        "baseUrl": ".",
+        "paths": {
+            "*": [
+                "node_modules/*",
+                "src/types/*"
+            ]
+        }
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
+    ]
+}