@sygnl/timestamp

Safe timestamp utilities for ad platforms with clock skew protection.

Install

npm install @sygnl/timestamp

Quick Start

import { getSafeTimestamp, formatGoogleTimestamp } from '@sygnl/timestamp';

// Prevent future timestamps (clock skew protection)
const eventTimestamp = Date.now() + 5000; // 5 seconds in the future
const safeTimestamp = getSafeTimestamp(eventTimestamp);
// Returns: Date.now() - 1000 (1 second ago, safe for ad platforms)

// Format for Google Ads
const googleTs = formatGoogleTimestamp(eventTimestamp);
// Returns: "2024-01-01 12:34:56+00:00"

Problem

Ad platforms (Meta, Google, Snapchat, TikTok, Bing) reject events with timestamps that are:

1. In the future (clock skew between servers)
2. Too close to "now" (platforms need processing buffer)

This causes conversion tracking failures and lost revenue.

Solution

This package ensures timestamps are always at least 1 second in the past, preventing rejections while maintaining accuracy.

Features

• Clock skew protection
• Platform-specific formatting (Google, Meta, etc.)
• Unix epoch conversion (ms and seconds)
• ISO 8601 formatting
• Time delta calculation
• Future timestamp detection
• Type-safe with TypeScript

API

getSafeTimestamp(timestampMs: number): number

Returns a safe timestamp in milliseconds, guaranteed to be in the past.

const future = Date.now() + 5000;
getSafeTimestamp(future);
// Returns: Date.now() - 1000

const past = Date.now() - 10000;
getSafeTimestamp(past);
// Returns: past (unchanged)

getSafeTimestampSeconds(timestampMs: number): number

Returns a safe timestamp in Unix epoch seconds (for Meta CAPI, Bing, etc.).

getSafeTimestampSeconds(1704067200000);
// Returns: 1704067199 (in seconds)

formatGoogleTimestamp(timestampMs: number): string

Formats timestamp for Google Ads: "YYYY-MM-DD HH:mm:ss+00:00"

formatGoogleTimestamp(1704067200000);
// Returns: "2024-01-01 00:00:00+00:00"

formatISO(timestampMs: number): string

Formats timestamp as ISO 8601: "YYYY-MM-DDTHH:mm:ss.sssZ"

formatISO(1704067200000);
// Returns: "2024-01-01T00:00:00.000Z"

getTimeDelta(timestampMs: number): number

Returns time difference between timestamp and now (for debugging).

const future = Date.now() + 5000;
getTimeDelta(future);
// Returns: ~5000 (5 seconds in the future)

const past = Date.now() - 10000;
getTimeDelta(past);
// Returns: ~-10000 (10 seconds in the past)

isFutureTimestamp(timestampMs: number, bufferMs?: number): boolean

Checks if timestamp is in the future.

const future = Date.now() + 1000;
isFutureTimestamp(future);
// Returns: true

Use Cases

Meta Conversions API

import { getSafeTimestampSeconds } from '@sygnl/timestamp';

const payload = {
  event_name: 'Purchase',
  event_time: getSafeTimestampSeconds(event.timestamp),
  user_data: { /* ... */ }
};

Google Ads Enhanced Conversions

import { formatGoogleTimestamp } from '@sygnl/timestamp';

const conversion = {
  conversionDateTime: formatGoogleTimestamp(event.timestamp),
  // ...
};

Universal Solution

import { getSafeTimestamp } from '@sygnl/timestamp';

// Works for all platforms
const safeTs = getSafeTimestamp(clientTimestamp);

// Then format as needed per platform

License

Apache-2.0

Copyright 2026 Edge Foundry, Inc.