s.plings.io Director Service - Implementation Guide

// /api/index.ts - Main entry point
import { VercelRequest, VercelResponse } from '@vercel/node';

export const config = {
  runtime: 'edge',
  regions: ['iad1', 'sfo1', 'sin1', 'syd1', 'hnd1', 'fra1'] // Global deployment
};

export default async function handler(req: VercelRequest) {
  const start = Date.now();
  
  try {
    // 1. Extract and validate parameters
    const params = extractParams(req.url);
    if (!validateParams(params)) {
      return redirectToError('invalid-params');
    }
    
    // 2. Security checks (rate limiting, etc.)
    const securityCheck = await performSecurityChecks(req, params);
    if (!securityCheck.passed) {
      return redirectToError(securityCheck.reason, securityCheck.status);
    }
    
    // 3. Verify identifier
    const verification = await verifyIdentifier(params);
    if (!verification.isValid) {
      await logFailedVerification(params, verification.reason);
      return redirectToError('invalid-identifier');
    }
    
    // 4. Log scan event (async, don't await)
    logScanEvent({
      ...params,
      ...verification,
      timestamp: Date.now(),
      headers: extractHeaders(req)
    }).catch(console.error);
    
    // 5. Resolve object (if exists)
    const resolution = await resolveObject(params.i);
    
    // 6. ROUTING LOGIC - THE HEART OF THE DIRECTOR
    const targetUrl = await determineRoute(params, verification, resolution, req);
    
    // 7. Redirect with enriched parameters
    return Response.redirect(targetUrl, 302);
    
  } catch (error) {
    console.error('Director error:', error);
    return redirectToError('system-error');
  } finally {
    console.log(`Scan handled in ${Date.now() - start}ms`);
  }
}

interface IncomingParams {
  t: 'q' | 'n' | 'r';      // Tag type
  i: string;               // Instance key (48 chars)
  p: string;               // HD wallet path
  cp?: string;             // Class pointer (11 chars)
  // Future: tx, svc, price, dur for direct commerce
}

interface OutgoingParams {
  oid?: string;            // Object UUID (when exists)
  ikey: string;            // Original instance key
  path: string;            // Base58 HD path
  class?: string;          // Class UUID (when resolved)
  cptr?: string;           // Class pointer
  src: 'scan';             // Source tracking
  loc?: string;            // GPS (if available)
  ts?: number;             // Timestamp
}

function enrichParameters(
  incoming: IncomingParams, 
  verification: VerificationResult,
  resolution: ObjectResolution
): URLSearchParams {
  const params = new URLSearchParams({
    ikey: incoming.i,
    path: incoming.p,
    src: 'scan'
  });
  
  if (incoming.cp) params.set('cptr', incoming.cp);
  if (resolution.objectId) params.set('oid', resolution.objectId);
  if (resolution.classId) params.set('class', resolution.classId);
  
  return params;
}

// /api/scan/verification.ts
import { generateClassPointer } from './crypto';

interface VerificationResult {
  isValid: boolean;
  identifierType?: 'generic' | 'manufacturer';
  manufacturerId?: number;
  classId?: string;
  reason?: string;
  cachedVerification?: boolean;
}

// Manufacturer Registry - Multiple storage strategies
class ManufacturerRegistryImpl {
  private cache = new Map<number, string>();
  private lastUpdate = 0;
  private readonly TTL = 3600000; // 1 hour
  
  async getPublicKey(manufacturerId: number): Promise<string | null> {
    // Check cache first
    if (this.cache.has(manufacturerId) && Date.now() - this.lastUpdate < this.TTL) {
      return this.cache.get(manufacturerId)!;
    }
    
    // Strategy 1: Edge Config (Vercel's solution for large configs)
    try {
      const edgeConfig = await import('@vercel/edge-config');
      const publicKey = await edgeConfig.get(`manufacturer_${manufacturerId}_pubkey`);
      if (publicKey) {
        this.cache.set(manufacturerId, publicKey as string);
        return publicKey as string;
      }
    } catch (e) {
      console.log('Edge Config not available');
    }
    
    // Strategy 2: KV Store (Vercel KV or Upstash Redis)
    try {
      const kv = await import('@vercel/kv');
      const publicKey = await kv.get(`mfr:pubkey:${manufacturerId}`);
      if (publicKey) {
        this.cache.set(manufacturerId, publicKey as string);
        return publicKey as string;
      }
    } catch (e) {
      console.log('KV store not available');
    }
    
    // Strategy 3: GraphQL API (with aggressive caching)
    try {
      const response = await fetch(process.env.PLINGS_API_ENDPOINT!, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Cache-Control': 'max-age=3600', // 1 hour cache
        },
        body: JSON.stringify({
          query: `
            query GetManufacturerPublicKey($manufacturerId: Int!) {
              manufacturer(id: $manufacturerId) {
                publicKey
              }
            }
          `,
          variables: { manufacturerId }
        })
      });
      
      if (response.ok) {
        const { data } = await response.json();
        if (data?.manufacturer?.publicKey) {
          const publicKey = data.manufacturer.publicKey;
          this.cache.set(manufacturerId, publicKey);
          this.lastUpdate = Date.now();
          return publicKey;
        }
      }
    } catch (e) {
      console.error('Failed to fetch public key from API:', e);
    }
    
    // Strategy 4: Fallback to essential manufacturers only
    const essentialManufacturers: Record<number, string> = {
      1: process.env.PLINGS_PUBLIC_KEY!,  // Always need Plings key
      // Only add top 5-10 manufacturers here
    };
    
    return essentialManufacturers[manufacturerId] || null;
  }
  
  // Batch load public keys on startup
  async preloadEssentialKeys(): Promise<void> {
    const essentialIds = [1, 3, 17, 42]; // Top manufacturers
    
    try {
      // Try to load from Edge Config
      const edgeConfig = await import('@vercel/edge-config');
      const keys = await edgeConfig.getAll();
      
      Object.entries(keys).forEach(([key, value]) => {
        const match = key.match(/^manufacturer_(\d+)_pubkey$/);
        if (match) {
          this.cache.set(parseInt(match[1]), value as string);
        }
      });
      
      this.lastUpdate = Date.now();
    } catch (e) {
      // Fallback to loading essential keys individually
      for (const id of essentialIds) {
        await this.getPublicKey(id);
      }
    }
  }
}

export const ManufacturerRegistry = new ManufacturerRegistryImpl();

// Initialize on cold start
ManufacturerRegistry.preloadEssentialKeys().catch(console.error);

export async function verifyIdentifier(
  params: IncomingParams
): Promise<VerificationResult> {
  const pathParts = params.p.split('.');
  const manufacturerId = parseInt(pathParts[1]);
  
  // Step 1: Get manufacturer public key
  const manufacturerKey = await ManufacturerRegistry.getPublicKey(manufacturerId);
  if (!manufacturerKey) {
    return { 
      isValid: false, 
      reason: 'Unknown manufacturer',
      manufacturerId 
    };
  }
  
  // Step 2: Verify class pointer if provided
  if (params.cp) {
    const pathToPointer = extractPathToPointer(params.p);
    const expectedPointer = generateClassPointer(manufacturerKey, pathToPointer);
    
    if (expectedPointer !== params.cp) {
      return {
        isValid: false,
        reason: 'Invalid class pointer',
        manufacturerId
      };
    }
  }
  
  // Step 3: For full instance verification, call API
  // This is deferred until after routing decision for performance
  return {
    isValid: true,
    identifierType: manufacturerId === 1 ? 'generic' : 'manufacturer',
    manufacturerId,
    cachedVerification: true
  };
}

// /api/scan/logging.ts
interface ScanEvent {
  // Required fields
  timestamp: number;
  instanceKey: string;
  path: string;
  tagType: 'q' | 'n' | 'r';
  
  // Verification results
  isValid: boolean;
  manufacturerId?: number;
  classPointer?: string;
  
  // Context
  userAgent: string;
  ipAddress: string;
  referer?: string;
  
  // Location (if available)
  latitude?: number;
  longitude?: number;
  accuracy?: number;
  
  // Routing decision
  routedTo: string;
  objectFound: boolean;
  authRequired: boolean;
}

export async function logScanEvent(event: ScanEvent): Promise<void> {
  // Use Vercel Edge Config or external service
  // Fire and forget for performance
  
  try {
    // Option 1: Vercel Analytics
    if (process.env.VERCEL_ANALYTICS_ID) {
      await fetch('https://vitals.vercel-insights.com/v1/events', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          eventName: 'scan',
          properties: event
        })
      });
    }
    
    // Option 2: Custom analytics endpoint
    if (process.env.ANALYTICS_ENDPOINT) {
      await fetch(process.env.ANALYTICS_ENDPOINT, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': process.env.ANALYTICS_API_KEY!
        },
        body: JSON.stringify(event)
      });
    }
  } catch (error) {
    // Log but don't throw - analytics shouldn't break routing
    console.error('Failed to log scan event:', error);
  }
}

// /lib/routing.ts - This will grow significantly over time
export async function determineRoute(
  params: ScanParams,
  verification: VerificationResult,
  resolution: ObjectResolution | null,
  request: Request
): Promise<string> {
  // Build enriched parameters for downstream services
  const outParams = enrichParameters(params, verification, resolution);
  
  // CASE 1: Unknown identifier
  if (!resolution || !resolution.exists) {
    return routeUnknownIdentifier(params, verification, outParams);
  }
  
  // CASE 2: Known object - Complex routing begins here
  const { object } = resolution;
  
  // Priority 1: Lost items always take precedence
  if (object.status?.includes('LOST')) {
    return `https://plings.io/found/${object.id}?${outParams}`;
  }
  
  // Priority 2: Multi-status handling (object can be for sale, rent, AND lend)
  const commerceRoute = determineCommerceRoute(object, params);
  if (commerceRoute) {
    return commerceRoute;
  }
  
  // Priority 3: Context-aware routing (future expansion)
  const contextualRoute = await determineContextualRoute(object, params, request);
  if (contextualRoute) {
    return contextualRoute;
  }
  
  // Priority 4: Visibility and auth requirements
  if (object.visibility === 'private' || resolution.requiresAuth) {
    return routeRequiringAuth(object, outParams);
  }
  
  // Default: Public object view
  return `https://plings.io/o/${object.id}?${outParams}`;
}

// Multi-status commerce routing (will expand significantly)
function determineCommerceRoute(object: ObjectData, params: ScanParams): string | null {
  const statuses = object.status || [];
  
  // Future: Complex logic for multi-status objects
  // For now, simple priority order
  if (statuses.includes('FOR_SALE')) {
    return `https://market.plings.io/item/${object.id}`;
  }
  if (statuses.includes('FOR_RENT')) {
    return `https://rent.plings.io/item/${object.id}`;
  }
  if (statuses.includes('LENDABLE')) {
    return `https://lend.plings.io/item/${object.id}`;
  }
  
  return null;
}

// Context-aware routing (future expansion area)
async function determineContextualRoute(
  object: ObjectData,
  params: ScanParams,
  request: Request
): Promise<string | null> {
  // Future considerations:
  // - Geographic location (scan at specific venue)
  // - Time of day (business hours vs after hours)
  // - Object class (special handling for certain types)
  // - User agent (mobile vs desktop)
  // - Previous scan history
  // - A/B testing groups
  
  // Example future logic:
  // if (object.class === 'TOOL' && isAtHardwareStore(request)) {
  //   return `https://plings.io/compare-prices/${object.id}`;
  // }
  
  return null;
}

// Version 1 (MVP): Simple priority order
if (status.includes('FOR_SALE')) return market;
if (status.includes('FOR_RENT')) return rent;
if (status.includes('LENDABLE')) return lend;

// Version 2: Consider price ratios
const salePrice = object.metadata.salePrice;
const rentPrice = object.metadata.rentPriceDaily;
if (salePrice && rentPrice) {
  const roi = rentPrice * 365 / salePrice;
  if (roi > 0.15) return rent; // Better ROI on renting
  return market;
}

// Version 3: Add location context
if (scanLocation.type === 'TOURIST_AREA') {
  return rent; // Tourists prefer renting
}
if (scanLocation.type === 'RESIDENTIAL') {
  return market; // Residents prefer buying
}

// Version 4: Machine learning model
const prediction = await routingModel.predict({
  object,
  location,
  timeOfDay,
  userAgent,
  historicalConversions
});
return prediction.optimalRoute;

// routing-config.ts - Externalize routing rules
export const ROUTING_RULES = {
  statusPriority: ['LOST', 'EMERGENCY', 'FOR_SALE', 'FOR_RENT', 'LENDABLE'],
  
  contextRules: [
    {
      condition: (obj) => obj.class === 'MEDICAL_DEVICE' && obj.status.includes('EMERGENCY'),
      route: 'https://emergency.plings.io/device/',
      priority: 1
    },
    {
      condition: (obj) => obj.manufacturerId === 17 && obj.status.includes('RECALL'),
      route: 'https://recall.plings.io/ikea/',
      priority: 2
    }
  ],
  
  // A/B test configuration
  experiments: {
    'new-found-flow': {
      enabled: true,
      percentage: 50,
      control: 'https://plings.io/found/',
      variant: 'https://plings.io/found-v2/'
    }
  }
};

// /api/scan/security.ts
import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

// Rate limiting configuration
const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(100, '1 m'), // 100 requests per minute
  analytics: true,
});

export const rateLimiter = {
  async check(req: Request): Promise<{ allowed: boolean; remaining: number }> {
    const ip = req.headers.get('x-forwarded-for') || 'unknown';
    const { success, remaining } = await ratelimit.limit(ip);
    
    return { allowed: success, remaining };
  }
};

// Input validation
export function validateParams(params: any): params is IncomingParams {
  // Required parameters
  if (!params.t || !params.i || !params.p) return false;
  
  // Type validation
  if (!['q', 'n', 'r'].includes(params.t)) return false;
  
  // Instance key format (48 chars, base58)
  if (!/^[1-9A-HJ-NP-Za-km-z]{44,48}$/.test(params.i)) return false;
  
  // Path format (dot-separated numbers/base58)
  if (!/^[1-9A-HJ-NP-Za-km-z]+(\.[1-9A-HJ-NP-Za-km-z]+)*$/.test(params.p)) return false;
  
  // Verify class pointer format (11 chars, base58)
  if (params.cp && !/^[1-9A-HJ-NP-Za-km-z]{11}$/.test(params.cp)) return false;
  
  return true;
}

// Error handling
export function redirectToError(reason: string, status = 302): Response {
  const errorUrls: Record<string, string> = {
    'invalid-params': 'https://plings.io/error/invalid-scan',
    'rate-limit': 'https://plings.io/error/too-many-requests',
    'invalid-identifier': 'https://plings.io/error/invalid-identifier',
    'system-error': 'https://plings.io/error/system',
  };
  
  return Response.redirect(
    errorUrls[reason] || errorUrls['system-error'],
    status
  );
}

// Store all manufacturer keys in Edge Config
// No environment variable limit, optimized for edge reading
{
  "manufacturer_1_pubkey": "Base58PublicKeyForPlings",
  "manufacturer_3_pubkey": "Base58PublicKeyForCocaCola",
  "manufacturer_17_pubkey": "Base58PublicKeyForIKEA",
  // ... hundreds more
}

// Serve from API with aggressive caching
// /api/manufacturers/registry.json
{
  "manufacturers": {
    "1": { "name": "Plings", "publicKey": "..." },
    "3": { "name": "Coca-Cola", "publicKey": "..." },
    "17": { "name": "IKEA", "publicKey": "..." }
  }
}

// Custom metrics for monitoring
interface DirectorMetrics {
  // Performance
  responseTime: Histogram;         // Target: <100ms p95
  verificationTime: Histogram;     // Target: <20ms
  routingTime: Histogram;         // Target: <10ms
  
  // Volume
  scanVolume: Counter;            // Total scans
  scanByType: Counter;            // QR vs NFC vs RFID
  scanByManufacturer: Counter;    // Per manufacturer
  scanByService: Counter;         // Where routed
  
  // Errors
  verificationFailures: Counter;   // Invalid identifiers
  routingErrors: Counter;         // Failed routing
  rateLimitHits: Counter;         // Rate limit rejections
  
  // Cache Performance
  cacheHitRate: Gauge;           // Object cache hits
  manufacturerCacheHits: Gauge;   // Public key cache
}

// Monitoring implementation
export function recordMetrics(event: string, value: number, tags?: Record<string, string>) {
  // Send to monitoring service
  if (process.env.MONITORING_ENABLED) {
    // DataDog, New Relic, or custom solution
  }
}

// /api/health
export default async function healthCheck(req: Request) {
  const checks = {
    edge: 'ok',
    redis: await checkRedis(),
    api: await checkAPI(),
    cache: await checkCache(),
  };
  
  const allHealthy = Object.values(checks).every(v => v === 'ok');
  
  return new Response(JSON.stringify({
    status: allHealthy ? 'healthy' : 'degraded',
    timestamp: new Date().toISOString(),
    checks,
    region: process.env.VERCEL_REGION,
  }), {
    status: allHealthy ? 200 : 503,
    headers: { 'Content-Type': 'application/json' }
  });
}

// __tests__/verification.test.ts
describe('Identifier Verification', () => {
  it('should verify valid class pointer', async () => {
    const params = {
      t: 'q',
      i: '4kyQCd5tMDjJVWJH5h95gUcjq3qTX2cj5nwjVyqBRwLo',
      p: '2.17.3.2.5.100.5000',
      cp: '4K7mX9abDcE'
    };
    
    const result = await verifyIdentifier(params);
    expect(result.isValid).toBe(true);
    expect(result.manufacturerId).toBe(17);
  });
  
  it('should reject invalid class pointer', async () => {
    const params = {
      t: 'q',
      i: '4kyQCd5tMDjJVWJH5h95gUcjq3qTX2cj5nwjVyqBRwLo',
      p: '2.17.3.2.5.100.5000',
      cp: 'INVALID123'
    };
    
    const result = await verifyIdentifier(params);
    expect(result.isValid).toBe(false);
    expect(result.reason).toBe('Invalid class pointer');
  });
});

// __tests__/routing.integration.test.ts
describe('Director Routing Integration', () => {
  it('should route FOR_SALE objects to marketplace', async () => {
    // Mock object resolution
    mockResolveObject({
      exists: true,
      object: {
        id: 'obj-123',
        status: ['FOR_SALE'],
        visibility: 'public'
      }
    });
    
    const response = await fetch('https://s.plings.io?t=q&i=TEST&p=2.1.1.1.1');
    
    expect(response.status).toBe(302);
    expect(response.headers.get('Location')).toContain('market.plings.io');
  });
});

interface PublicObjectPageProps {
  // URL params
  objectId: string;
  
  // Query params from scan
  ikey?: string;      // Instance key (for verification)
  path?: string;      // HD path
  src?: string;       // Source (always 'scan' from Director)
}

// Display requirements
- Object name and main image
- Public description
- Owner organization (not personal info)
- Object status badges (if public)
- [Contact Owner] button (if enabled)
- [Report Found] if status includes 'lost'
- [View in App] call-to-action for non-users
- Share buttons for social media

// When redirected from scan requiring auth
interface LoginPageScanContext {
  return: 'scan';
  state: string;  // Encoded scan parameters
}

// After successful login:
1. Decode state parameters
2. Call GraphQL to re-verify access
3. Redirect to appropriate view based on permissions