@kido/instant-galleryCopy Anchor Link

Architecture Paradigm: Cryptographic HMAC QR Pass + Watermarked 720p WebP Preview + Viral Lead Gatekeeper + Zero-Egress R2 Presigned Downloads.

💥 The Real-World Bottleneck (Why It Exists)Copy Anchor Link

In high-profile enterprise events, weddings, corporate galas, and interactive Glambot 360 / Photobooth setups:

1. Bandwidth Exhaustion & Server Crashes During Peak Moments:
   • Event guests (500–2,000 attendees) scan QR codes printed on physical photos within minutes of each other.
   • If 4K 240fps video files (80MB–150MB each) are streamed directly from the application origin, a standard 100Mbps VPS network port is saturated in seconds, resulting in immediate connection resets and 504 Gateway Timeouts.
2. Leaked VIP Privacy & Zero Access Control:
   • Naïve implementations dump media into public Google Drive folders or unauthenticated public S3 buckets. VIP guests' candid photos become indexed by search engines or accessible to unauthorized attendees.
3. Lost Marketing Opportunity & Zero Lead Capture:
   • Providing direct unauthenticated file download links forfeits the opportunity to collect qualified enterprise attendee information (phone numbers, corporate emails, social profiles).

🏛️ 3-Tier Production Evolution LadderCopy Anchor Link

📐 Architecture & Data FlowCopy Anchor Link

📦 Architecture & Core API ExportsCopy Anchor Link

All capabilities are strictly isolated in packages/instant-gallery:

1. src/token-manager.tsCopy Anchor Link

• TokenManager: Cryptographic HMAC-SHA256 QR pass generator and verifier.
• generateGuestQrToken(eventId, guestId, tableId, options): Produces tamper-proof short tokens suitable for printing on 58mm/80mm thermal receipts.
• verifyGuestQrToken(token): Verifies token integrity and expiration without needing database lookups.

2. src/lead-gatekeeper.tsCopy Anchor Link

• captureLead(pass, leadInfo): Validates guest data (standardizing Vietnamese phone numbers 09x / 08x), unlocks full-resolution downloads, and stores consent audit trails.
• validateVietnamesePhone(phone): Strict regex validator for Vietnamese telecom prefixes.

3. src/storage-signer.tsCopy Anchor Link

• generateDownloadUrl(mediaItem, pass): Generates time-limited presigned download URLs directly from Cloudflare R2 / AWS S3 buckets.
• UnauthorizedTierError: Thrown when an unverified guest attempts to bypass the lead form to download master 4K media.

4. src/watermark-engine.tsCopy Anchor Link

• WatermarkEngine: Helper producing SVG and Canvas brand overlays for preview assets.

💻 Production Implementation & Code SnippetCopy Anchor Link

Complete Event Media Pipeline (src/services/event-media-service.ts)Copy Anchor Link

import {
  TokenManager,
  generateGuestQrToken,
  captureLead,
  generateDownloadUrl,
  UnauthorizedTierError,
} from '@kido/instant-gallery';

// 1. Initialize TokenManager with an enterprise HMAC secret
const tokenManager = new TokenManager({
  secretKey: process.env.GALLERY_HMAC_SECRET || 'secret-salt-2026',
  ttlSeconds: 7 * 24 * 3600, // 7-day validity
});

// 2. Photobooth generates receipt QR pass upon photo capture
export function handlePhotoCaptured(eventId: string, tableCode: string) {
  const guestPass = generateGuestQrToken(eventId, `guest_${Date.now()}`, tableCode, {
    shortUrlPrefix: 'https://gallery.example.com/g',
  });

  console.log('[K80 Thermal Printer] Embed QR:', guestPass.qrPayload);
  return guestPass;
}

// 3. Guest visits gallery: Server checks access level
export async function getMediaForGuest(guestToken: string, mediaRecord: any) {
  const verifiedPass = tokenManager.verify(guestToken);
  if (!verifiedPass.isValid) {
    throw new Error('Invalid or expired QR pass');
  }

  // If user hasn't completed lead capture, deliver watermarked preview only
  if (!verifiedPass.isUnlocked) {
    return {
      status: 'LOCKED',
      previewUrl: mediaRecord.watermarkedWebpUrl,
      requiresLeadForm: true,
    };
  }

  // If unlocked, generate temporary presigned download link for 4K video
  const downloadInfo = generateDownloadUrl(mediaRecord, verifiedPass, {
    expiresInSeconds: 3600,
  });

  return {
    status: 'UNLOCKED',
    downloadUrl: downloadInfo.url,
  };
}

// 4. Guest completes lead capture form to unlock 4K download
export async function handleLeadSubmission(guestToken: string, formData: any) {
  const verifiedPass = tokenManager.verify(guestToken);

  const captureResult = await captureLead(verifiedPass, {
    fullName: formData.name,
    phoneNumber: formData.phone, // Automatically normalized to "0912345678"
    email: formData.email,
    marketingConsent: true,
  });

  return {
    success: true,
    unlockedToken: captureResult.newUnlockedToken,
  };
}

⚡ Benchmark & Verified PerformanceCopy Anchor Link

Benchmarked during a 1,500-guest live corporate gala:

🚀 Surgical Extraction & CLI InstallationCopy Anchor Link

npx @kido/cli add instant-gallery