@sygnl/timestamp 1.0.0

package/README.md

@@ -0,0 +1,156 @@
+# @sygnl/timestamp
+
+Safe timestamp utilities for ad platforms with clock skew protection.
+
+## Install
+
+```bash
+npm install @sygnl/timestamp
+```
+
+## Quick Start
+
+```typescript
+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.
+
+```typescript
+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.).
+
+```typescript
+getSafeTimestampSeconds(1704067200000);
+// Returns: 1704067199 (in seconds)
+```
+
+### `formatGoogleTimestamp(timestampMs: number): string`
+
+Formats timestamp for Google Ads: "YYYY-MM-DD HH:mm:ss+00:00"
+
+```typescript
+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"
+
+```typescript
+formatISO(1704067200000);
+// Returns: "2024-01-01T00:00:00.000Z"
+```
+
+### `getTimeDelta(timestampMs: number): number`
+
+Returns time difference between timestamp and now (for debugging).
+
+```typescript
+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.
+
+```typescript
+const future = Date.now() + 1000;
+isFutureTimestamp(future);
+// Returns: true
+```
+
+## Use Cases
+
+### Meta Conversions API
+
+```typescript
+import { getSafeTimestampSeconds } from '@sygnl/timestamp';
+
+const payload = {
+  event_name: 'Purchase',
+  event_time: getSafeTimestampSeconds(event.timestamp),
+  user_data: { /* ... */ }
+};
+```
+
+### Google Ads Enhanced Conversions
+
+```typescript
+import { formatGoogleTimestamp } from '@sygnl/timestamp';
+
+const conversion = {
+  conversionDateTime: formatGoogleTimestamp(event.timestamp),
+  // ...
+};
+```
+
+### Universal Solution
+
+```typescript
+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.

package/dist/index.cjs

@@ -0,0 +1,67 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  formatGoogleTimestamp: () => formatGoogleTimestamp,
+  formatISO: () => formatISO,
+  getSafeTimestamp: () => getSafeTimestamp,
+  getSafeTimestampSeconds: () => getSafeTimestampSeconds,
+  getTimeDelta: () => getTimeDelta,
+  isFutureTimestamp: () => isFutureTimestamp
+});
+module.exports = __toCommonJS(index_exports);
+function getSafeTimestamp(timestampMs) {
+  return Math.min(timestampMs, Date.now() - 1e3);
+}
+function getSafeTimestampSeconds(timestampMs) {
+  return Math.floor(getSafeTimestamp(timestampMs) / 1e3);
+}
+function formatGoogleTimestamp(timestampMs) {
+  const safeTimestamp = getSafeTimestamp(timestampMs);
+  const date = new Date(safeTimestamp);
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(date.getUTCDate()).padStart(2, "0");
+  const hours = String(date.getUTCHours()).padStart(2, "0");
+  const minutes = String(date.getUTCMinutes()).padStart(2, "0");
+  const seconds = String(date.getUTCSeconds()).padStart(2, "0");
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}+00:00`;
+}
+function formatISO(timestampMs) {
+  const safeTimestamp = getSafeTimestamp(timestampMs);
+  return new Date(safeTimestamp).toISOString();
+}
+function getTimeDelta(timestampMs) {
+  return timestampMs - Date.now();
+}
+function isFutureTimestamp(timestampMs, bufferMs = 0) {
+  return timestampMs > Date.now() + bufferMs;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  formatGoogleTimestamp,
+  formatISO,
+  getSafeTimestamp,
+  getSafeTimestampSeconds,
+  getTimeDelta,
+  isFutureTimestamp
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @sygnl/timestamp\n * \n * Safe timestamp utilities for ad platforms with clock skew protection.\n * \n * Prevents timestamp rejections from ad platform APIs (Google, Meta, Snapchat, TikTok, etc.)\n * by ensuring timestamps are never in the future and include a processing buffer.\n * \n * @example\n * ```typescript\n * import { getSafeTimestamp, formatGoogleTimestamp } from '@sygnl/timestamp';\n * \n * // Prevent future timestamps\n * const safeTs = getSafeTimestamp(eventTimestamp);\n * \n * // Format for Google Ads\n * const googleTs = formatGoogleTimestamp(eventTimestamp);\n * ```\n */\n\n/**\n * Get a safe timestamp that will never be rejected by ad platforms\n * \n * Ad platforms reject timestamps that are:\n * - In the future (due to clock skew between servers)\n * - Too close to \"now\" (platforms need processing buffer)\n * \n * This function ensures the timestamp is always at least 1 second in the past.\n * \n * @param timestampMs - The original event timestamp in milliseconds\n * @returns A safe timestamp in milliseconds, guaranteed to be in the past\n * \n * @example\n * ```typescript\n * const now = Date.now();\n * const future = now + 5000; // 5 seconds in the future\n * \n * getSafeTimestamp(future);\n * // Returns: Date.now() - 1000 (1 second ago)\n * \n * const past = now - 10000; // 10 seconds ago\n * getSafeTimestamp(past);\n * // Returns: past (unchanged)\n * ```\n */\nexport function getSafeTimestamp(timestampMs: number): number {\n  // Use Math.min to cap at \"now - 1 second\"\n  // This prevents future timestamps and adds a safety buffer\n  return Math.min(timestampMs, Date.now() - 1000);\n}\n\n/**\n * Get safe timestamp in seconds (Unix epoch)\n * \n * Many ad platforms (Meta, Bing, Google) expect timestamps in seconds.\n * This is a convenience function that converts ms → seconds safely.\n * \n * @param timestampMs - The original event timestamp in milliseconds\n * @returns A safe timestamp in seconds (Unix epoch)\n * \n * @example\n * ```typescript\n * const now = Date.now(); // 1704067200000\n * getSafeTimestampSeconds(now);\n * // Returns: 1704067199 (1 second ago, in seconds)\n * ```\n */\nexport function getSafeTimestampSeconds(timestampMs: number): number {\n  return Math.floor(getSafeTimestamp(timestampMs) / 1000);\n}\n\n/**\n * Format safe timestamp as ISO 8601 string for Google Ads\n * \n * Google Ads requires: \"YYYY-MM-DD HH:mm:ss+00:00\"\n * \n * @param timestampMs - The original event timestamp in milliseconds\n * @returns ISO 8601 formatted string in UTC\n * \n * @example\n * ```typescript\n * formatGoogleTimestamp(1704067200000);\n * // Returns: \"2024-01-01 00:00:00+00:00\"\n * ```\n */\nexport function formatGoogleTimestamp(timestampMs: number): string {\n  const safeTimestamp = getSafeTimestamp(timestampMs);\n  const date = new Date(safeTimestamp);\n  \n  const year = date.getUTCFullYear();\n  const month = String(date.getUTCMonth() + 1).padStart(2, '0');\n  const day = String(date.getUTCDate()).padStart(2, '0');\n  const hours = String(date.getUTCHours()).padStart(2, '0');\n  const minutes = String(date.getUTCMinutes()).padStart(2, '0');\n  const seconds = String(date.getUTCSeconds()).padStart(2, '0');\n  \n  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}+00:00`;\n}\n\n/**\n * Format safe timestamp as ISO 8601 string (standard format)\n * \n * Returns: \"YYYY-MM-DDTHH:mm:ss.sssZ\"\n * \n * @param timestampMs - The original event timestamp in milliseconds\n * @returns ISO 8601 formatted string with milliseconds\n * \n * @example\n * ```typescript\n * formatISO(1704067200000);\n * // Returns: \"2024-01-01T00:00:00.000Z\"\n * ```\n */\nexport function formatISO(timestampMs: number): string {\n  const safeTimestamp = getSafeTimestamp(timestampMs);\n  return new Date(safeTimestamp).toISOString();\n}\n\n/**\n * Get time difference between event timestamp and now\n * \n * Useful for debugging clock skew issues.\n * \n * @param timestampMs - The event timestamp in milliseconds\n * @returns Difference in milliseconds (positive = future, negative = past)\n * \n * @example\n * ```typescript\n * const future = Date.now() + 5000;\n * getTimeDelta(future);\n * // Returns: ~5000 (5 seconds in the future)\n * \n * const past = Date.now() - 10000;\n * getTimeDelta(past);\n * // Returns: ~-10000 (10 seconds in the past)\n * ```\n */\nexport function getTimeDelta(timestampMs: number): number {\n  return timestampMs - Date.now();\n}\n\n/**\n * Check if timestamp is in the future (has clock skew)\n * \n * @param timestampMs - The event timestamp in milliseconds\n * @param bufferMs - Buffer in milliseconds (default: 0)\n * @returns true if timestamp is in the future\n * \n * @example\n * ```typescript\n * const future = Date.now() + 1000;\n * isFutureTimestamp(future);\n * // Returns: true\n * ```\n */\nexport function isFutureTimestamp(timestampMs: number, bufferMs: number = 0): boolean {\n  return timestampMs > Date.now() + bufferMs;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA6CO,SAAS,iBAAiB,aAA6B;AAG5D,SAAO,KAAK,IAAI,aAAa,KAAK,IAAI,IAAI,GAAI;AAChD;AAkBO,SAAS,wBAAwB,aAA6B;AACnE,SAAO,KAAK,MAAM,iBAAiB,WAAW,IAAI,GAAI;AACxD;AAgBO,SAAS,sBAAsB,aAA6B;AACjE,QAAM,gBAAgB,iBAAiB,WAAW;AAClD,QAAM,OAAO,IAAI,KAAK,aAAa;AAEnC,QAAM,OAAO,KAAK,eAAe;AACjC,QAAM,QAAQ,OAAO,KAAK,YAAY,IAAI,CAAC,EAAE,SAAS,GAAG,GAAG;AAC5D,QAAM,MAAM,OAAO,KAAK,WAAW,CAAC,EAAE,SAAS,GAAG,GAAG;AACrD,QAAM,QAAQ,OAAO,KAAK,YAAY,CAAC,EAAE,SAAS,GAAG,GAAG;AACxD,QAAM,UAAU,OAAO,KAAK,cAAc,CAAC,EAAE,SAAS,GAAG,GAAG;AAC5D,QAAM,UAAU,OAAO,KAAK,cAAc,CAAC,EAAE,SAAS,GAAG,GAAG;AAE5D,SAAO,GAAG,IAAI,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,OAAO,IAAI,OAAO;AAC/D;AAgBO,SAAS,UAAU,aAA6B;AACrD,QAAM,gBAAgB,iBAAiB,WAAW;AAClD,SAAO,IAAI,KAAK,aAAa,EAAE,YAAY;AAC7C;AAqBO,SAAS,aAAa,aAA6B;AACxD,SAAO,cAAc,KAAK,IAAI;AAChC;AAgBO,SAAS,kBAAkB,aAAqB,WAAmB,GAAY;AACpF,SAAO,cAAc,KAAK,IAAI,IAAI;AACpC;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,129 @@
+/**
+ * @sygnl/timestamp
+ *
+ * Safe timestamp utilities for ad platforms with clock skew protection.
+ *
+ * Prevents timestamp rejections from ad platform APIs (Google, Meta, Snapchat, TikTok, etc.)
+ * by ensuring timestamps are never in the future and include a processing buffer.
+ *
+ * @example
+ * ```typescript
+ * import { getSafeTimestamp, formatGoogleTimestamp } from '@sygnl/timestamp';
+ *
+ * // Prevent future timestamps
+ * const safeTs = getSafeTimestamp(eventTimestamp);
+ *
+ * // Format for Google Ads
+ * const googleTs = formatGoogleTimestamp(eventTimestamp);
+ * ```
+ */
+/**
+ * Get a safe timestamp that will never be rejected by ad platforms
+ *
+ * Ad platforms reject timestamps that are:
+ * - In the future (due to clock skew between servers)
+ * - Too close to "now" (platforms need processing buffer)
+ *
+ * This function ensures the timestamp is always at least 1 second in the past.
+ *
+ * @param timestampMs - The original event timestamp in milliseconds
+ * @returns A safe timestamp in milliseconds, guaranteed to be in the past
+ *
+ * @example
+ * ```typescript
+ * const now = Date.now();
+ * const future = now + 5000; // 5 seconds in the future
+ *
+ * getSafeTimestamp(future);
+ * // Returns: Date.now() - 1000 (1 second ago)
+ *
+ * const past = now - 10000; // 10 seconds ago
+ * getSafeTimestamp(past);
+ * // Returns: past (unchanged)
+ * ```
+ */
+declare function getSafeTimestamp(timestampMs: number): number;
+/**
+ * Get safe timestamp in seconds (Unix epoch)
+ *
+ * Many ad platforms (Meta, Bing, Google) expect timestamps in seconds.
+ * This is a convenience function that converts ms → seconds safely.
+ *
+ * @param timestampMs - The original event timestamp in milliseconds
+ * @returns A safe timestamp in seconds (Unix epoch)
+ *
+ * @example
+ * ```typescript
+ * const now = Date.now(); // 1704067200000
+ * getSafeTimestampSeconds(now);
+ * // Returns: 1704067199 (1 second ago, in seconds)
+ * ```
+ */
+declare function getSafeTimestampSeconds(timestampMs: number): number;
+/**
+ * Format safe timestamp as ISO 8601 string for Google Ads
+ *
+ * Google Ads requires: "YYYY-MM-DD HH:mm:ss+00:00"
+ *
+ * @param timestampMs - The original event timestamp in milliseconds
+ * @returns ISO 8601 formatted string in UTC
+ *
+ * @example
+ * ```typescript
+ * formatGoogleTimestamp(1704067200000);
+ * // Returns: "2024-01-01 00:00:00+00:00"
+ * ```
+ */
+declare function formatGoogleTimestamp(timestampMs: number): string;
+/**
+ * Format safe timestamp as ISO 8601 string (standard format)
+ *
+ * Returns: "YYYY-MM-DDTHH:mm:ss.sssZ"
+ *
+ * @param timestampMs - The original event timestamp in milliseconds
+ * @returns ISO 8601 formatted string with milliseconds
+ *
+ * @example
+ * ```typescript
+ * formatISO(1704067200000);
+ * // Returns: "2024-01-01T00:00:00.000Z"
+ * ```
+ */
+declare function formatISO(timestampMs: number): string;
+/**
+ * Get time difference between event timestamp and now
+ *
+ * Useful for debugging clock skew issues.
+ *
+ * @param timestampMs - The event timestamp in milliseconds
+ * @returns Difference in milliseconds (positive = future, negative = past)
+ *
+ * @example
+ * ```typescript
+ * 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)
+ * ```
+ */
+declare function getTimeDelta(timestampMs: number): number;
+/**
+ * Check if timestamp is in the future (has clock skew)
+ *
+ * @param timestampMs - The event timestamp in milliseconds
+ * @param bufferMs - Buffer in milliseconds (default: 0)
+ * @returns true if timestamp is in the future
+ *
+ * @example
+ * ```typescript
+ * const future = Date.now() + 1000;
+ * isFutureTimestamp(future);
+ * // Returns: true
+ * ```
+ */
+declare function isFutureTimestamp(timestampMs: number, bufferMs?: number): boolean;
+
+export { formatGoogleTimestamp, formatISO, getSafeTimestamp, getSafeTimestampSeconds, getTimeDelta, isFutureTimestamp };

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @sygnl/timestamp
+ *
+ * Safe timestamp utilities for ad platforms with clock skew protection.
+ *
+ * Prevents timestamp rejections from ad platform APIs (Google, Meta, Snapchat, TikTok, etc.)
+ * by ensuring timestamps are never in the future and include a processing buffer.
+ *
+ * @example
+ * ```typescript
+ * import { getSafeTimestamp, formatGoogleTimestamp } from '@sygnl/timestamp';
+ *
+ * // Prevent future timestamps
+ * const safeTs = getSafeTimestamp(eventTimestamp);
+ *
+ * // Format for Google Ads
+ * const googleTs = formatGoogleTimestamp(eventTimestamp);
+ * ```
+ */
+/**
+ * Get a safe timestamp that will never be rejected by ad platforms
+ *
+ * Ad platforms reject timestamps that are:
+ * - In the future (due to clock skew between servers)
+ * - Too close to "now" (platforms need processing buffer)
+ *
+ * This function ensures the timestamp is always at least 1 second in the past.
+ *
+ * @param timestampMs - The original event timestamp in milliseconds
+ * @returns A safe timestamp in milliseconds, guaranteed to be in the past
+ *
+ * @example
+ * ```typescript
+ * const now = Date.now();
+ * const future = now + 5000; // 5 seconds in the future
+ *
+ * getSafeTimestamp(future);
+ * // Returns: Date.now() - 1000 (1 second ago)
+ *
+ * const past = now - 10000; // 10 seconds ago
+ * getSafeTimestamp(past);
+ * // Returns: past (unchanged)
+ * ```
+ */
+declare function getSafeTimestamp(timestampMs: number): number;
+/**
+ * Get safe timestamp in seconds (Unix epoch)
+ *
+ * Many ad platforms (Meta, Bing, Google) expect timestamps in seconds.
+ * This is a convenience function that converts ms → seconds safely.
+ *
+ * @param timestampMs - The original event timestamp in milliseconds
+ * @returns A safe timestamp in seconds (Unix epoch)
+ *
+ * @example
+ * ```typescript
+ * const now = Date.now(); // 1704067200000
+ * getSafeTimestampSeconds(now);
+ * // Returns: 1704067199 (1 second ago, in seconds)
+ * ```
+ */
+declare function getSafeTimestampSeconds(timestampMs: number): number;
+/**
+ * Format safe timestamp as ISO 8601 string for Google Ads
+ *
+ * Google Ads requires: "YYYY-MM-DD HH:mm:ss+00:00"
+ *
+ * @param timestampMs - The original event timestamp in milliseconds
+ * @returns ISO 8601 formatted string in UTC
+ *
+ * @example
+ * ```typescript
+ * formatGoogleTimestamp(1704067200000);
+ * // Returns: "2024-01-01 00:00:00+00:00"
+ * ```
+ */
+declare function formatGoogleTimestamp(timestampMs: number): string;
+/**
+ * Format safe timestamp as ISO 8601 string (standard format)
+ *
+ * Returns: "YYYY-MM-DDTHH:mm:ss.sssZ"
+ *
+ * @param timestampMs - The original event timestamp in milliseconds
+ * @returns ISO 8601 formatted string with milliseconds
+ *
+ * @example
+ * ```typescript
+ * formatISO(1704067200000);
+ * // Returns: "2024-01-01T00:00:00.000Z"
+ * ```
+ */
+declare function formatISO(timestampMs: number): string;
+/**
+ * Get time difference between event timestamp and now
+ *
+ * Useful for debugging clock skew issues.
+ *
+ * @param timestampMs - The event timestamp in milliseconds
+ * @returns Difference in milliseconds (positive = future, negative = past)
+ *
+ * @example
+ * ```typescript
+ * 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)
+ * ```
+ */
+declare function getTimeDelta(timestampMs: number): number;
+/**
+ * Check if timestamp is in the future (has clock skew)
+ *
+ * @param timestampMs - The event timestamp in milliseconds
+ * @param bufferMs - Buffer in milliseconds (default: 0)
+ * @returns true if timestamp is in the future
+ *
+ * @example
+ * ```typescript
+ * const future = Date.now() + 1000;
+ * isFutureTimestamp(future);
+ * // Returns: true
+ * ```
+ */
+declare function isFutureTimestamp(timestampMs: number, bufferMs?: number): boolean;
+
+export { formatGoogleTimestamp, formatISO, getSafeTimestamp, getSafeTimestampSeconds, getTimeDelta, isFutureTimestamp };

package/dist/index.js

@@ -0,0 +1,37 @@
+// src/index.ts
+function getSafeTimestamp(timestampMs) {
+  return Math.min(timestampMs, Date.now() - 1e3);
+}
+function getSafeTimestampSeconds(timestampMs) {
+  return Math.floor(getSafeTimestamp(timestampMs) / 1e3);
+}
+function formatGoogleTimestamp(timestampMs) {
+  const safeTimestamp = getSafeTimestamp(timestampMs);
+  const date = new Date(safeTimestamp);
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(date.getUTCDate()).padStart(2, "0");
+  const hours = String(date.getUTCHours()).padStart(2, "0");
+  const minutes = String(date.getUTCMinutes()).padStart(2, "0");
+  const seconds = String(date.getUTCSeconds()).padStart(2, "0");
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}+00:00`;
+}
+function formatISO(timestampMs) {
+  const safeTimestamp = getSafeTimestamp(timestampMs);
+  return new Date(safeTimestamp).toISOString();
+}
+function getTimeDelta(timestampMs) {
+  return timestampMs - Date.now();
+}
+function isFutureTimestamp(timestampMs, bufferMs = 0) {
+  return timestampMs > Date.now() + bufferMs;
+}
+export {
+  formatGoogleTimestamp,
+  formatISO,
+  getSafeTimestamp,
+  getSafeTimestampSeconds,
+  getTimeDelta,
+  isFutureTimestamp
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @sygnl/timestamp\n * \n * Safe timestamp utilities for ad platforms with clock skew protection.\n * \n * Prevents timestamp rejections from ad platform APIs (Google, Meta, Snapchat, TikTok, etc.)\n * by ensuring timestamps are never in the future and include a processing buffer.\n * \n * @example\n * ```typescript\n * import { getSafeTimestamp, formatGoogleTimestamp } from '@sygnl/timestamp';\n * \n * // Prevent future timestamps\n * const safeTs = getSafeTimestamp(eventTimestamp);\n * \n * // Format for Google Ads\n * const googleTs = formatGoogleTimestamp(eventTimestamp);\n * ```\n */\n\n/**\n * Get a safe timestamp that will never be rejected by ad platforms\n * \n * Ad platforms reject timestamps that are:\n * - In the future (due to clock skew between servers)\n * - Too close to \"now\" (platforms need processing buffer)\n * \n * This function ensures the timestamp is always at least 1 second in the past.\n * \n * @param timestampMs - The original event timestamp in milliseconds\n * @returns A safe timestamp in milliseconds, guaranteed to be in the past\n * \n * @example\n * ```typescript\n * const now = Date.now();\n * const future = now + 5000; // 5 seconds in the future\n * \n * getSafeTimestamp(future);\n * // Returns: Date.now() - 1000 (1 second ago)\n * \n * const past = now - 10000; // 10 seconds ago\n * getSafeTimestamp(past);\n * // Returns: past (unchanged)\n * ```\n */\nexport function getSafeTimestamp(timestampMs: number): number {\n  // Use Math.min to cap at \"now - 1 second\"\n  // This prevents future timestamps and adds a safety buffer\n  return Math.min(timestampMs, Date.now() - 1000);\n}\n\n/**\n * Get safe timestamp in seconds (Unix epoch)\n * \n * Many ad platforms (Meta, Bing, Google) expect timestamps in seconds.\n * This is a convenience function that converts ms → seconds safely.\n * \n * @param timestampMs - The original event timestamp in milliseconds\n * @returns A safe timestamp in seconds (Unix epoch)\n * \n * @example\n * ```typescript\n * const now = Date.now(); // 1704067200000\n * getSafeTimestampSeconds(now);\n * // Returns: 1704067199 (1 second ago, in seconds)\n * ```\n */\nexport function getSafeTimestampSeconds(timestampMs: number): number {\n  return Math.floor(getSafeTimestamp(timestampMs) / 1000);\n}\n\n/**\n * Format safe timestamp as ISO 8601 string for Google Ads\n * \n * Google Ads requires: \"YYYY-MM-DD HH:mm:ss+00:00\"\n * \n * @param timestampMs - The original event timestamp in milliseconds\n * @returns ISO 8601 formatted string in UTC\n * \n * @example\n * ```typescript\n * formatGoogleTimestamp(1704067200000);\n * // Returns: \"2024-01-01 00:00:00+00:00\"\n * ```\n */\nexport function formatGoogleTimestamp(timestampMs: number): string {\n  const safeTimestamp = getSafeTimestamp(timestampMs);\n  const date = new Date(safeTimestamp);\n  \n  const year = date.getUTCFullYear();\n  const month = String(date.getUTCMonth() + 1).padStart(2, '0');\n  const day = String(date.getUTCDate()).padStart(2, '0');\n  const hours = String(date.getUTCHours()).padStart(2, '0');\n  const minutes = String(date.getUTCMinutes()).padStart(2, '0');\n  const seconds = String(date.getUTCSeconds()).padStart(2, '0');\n  \n  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}+00:00`;\n}\n\n/**\n * Format safe timestamp as ISO 8601 string (standard format)\n * \n * Returns: \"YYYY-MM-DDTHH:mm:ss.sssZ\"\n * \n * @param timestampMs - The original event timestamp in milliseconds\n * @returns ISO 8601 formatted string with milliseconds\n * \n * @example\n * ```typescript\n * formatISO(1704067200000);\n * // Returns: \"2024-01-01T00:00:00.000Z\"\n * ```\n */\nexport function formatISO(timestampMs: number): string {\n  const safeTimestamp = getSafeTimestamp(timestampMs);\n  return new Date(safeTimestamp).toISOString();\n}\n\n/**\n * Get time difference between event timestamp and now\n * \n * Useful for debugging clock skew issues.\n * \n * @param timestampMs - The event timestamp in milliseconds\n * @returns Difference in milliseconds (positive = future, negative = past)\n * \n * @example\n * ```typescript\n * const future = Date.now() + 5000;\n * getTimeDelta(future);\n * // Returns: ~5000 (5 seconds in the future)\n * \n * const past = Date.now() - 10000;\n * getTimeDelta(past);\n * // Returns: ~-10000 (10 seconds in the past)\n * ```\n */\nexport function getTimeDelta(timestampMs: number): number {\n  return timestampMs - Date.now();\n}\n\n/**\n * Check if timestamp is in the future (has clock skew)\n * \n * @param timestampMs - The event timestamp in milliseconds\n * @param bufferMs - Buffer in milliseconds (default: 0)\n * @returns true if timestamp is in the future\n * \n * @example\n * ```typescript\n * const future = Date.now() + 1000;\n * isFutureTimestamp(future);\n * // Returns: true\n * ```\n */\nexport function isFutureTimestamp(timestampMs: number, bufferMs: number = 0): boolean {\n  return timestampMs > Date.now() + bufferMs;\n}\n"],"mappings":";AA6CO,SAAS,iBAAiB,aAA6B;AAG5D,SAAO,KAAK,IAAI,aAAa,KAAK,IAAI,IAAI,GAAI;AAChD;AAkBO,SAAS,wBAAwB,aAA6B;AACnE,SAAO,KAAK,MAAM,iBAAiB,WAAW,IAAI,GAAI;AACxD;AAgBO,SAAS,sBAAsB,aAA6B;AACjE,QAAM,gBAAgB,iBAAiB,WAAW;AAClD,QAAM,OAAO,IAAI,KAAK,aAAa;AAEnC,QAAM,OAAO,KAAK,eAAe;AACjC,QAAM,QAAQ,OAAO,KAAK,YAAY,IAAI,CAAC,EAAE,SAAS,GAAG,GAAG;AAC5D,QAAM,MAAM,OAAO,KAAK,WAAW,CAAC,EAAE,SAAS,GAAG,GAAG;AACrD,QAAM,QAAQ,OAAO,KAAK,YAAY,CAAC,EAAE,SAAS,GAAG,GAAG;AACxD,QAAM,UAAU,OAAO,KAAK,cAAc,CAAC,EAAE,SAAS,GAAG,GAAG;AAC5D,QAAM,UAAU,OAAO,KAAK,cAAc,CAAC,EAAE,SAAS,GAAG,GAAG;AAE5D,SAAO,GAAG,IAAI,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,OAAO,IAAI,OAAO;AAC/D;AAgBO,SAAS,UAAU,aAA6B;AACrD,QAAM,gBAAgB,iBAAiB,WAAW;AAClD,SAAO,IAAI,KAAK,aAAa,EAAE,YAAY;AAC7C;AAqBO,SAAS,aAAa,aAA6B;AACxD,SAAO,cAAc,KAAK,IAAI;AAChC;AAgBO,SAAS,kBAAkB,aAAqB,WAAmB,GAAY;AACpF,SAAO,cAAc,KAAK,IAAI,IAAI;AACpC;","names":[]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@sygnl/timestamp",
+  "version": "1.0.0",
+  "description": "Safe timestamp utilities for ad platforms with clock skew protection",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "timestamp",
+    "clock-skew",
+    "ad-platforms",
+    "meta",
+    "google",
+    "snapchat",
+    "tiktok",
+    "time",
+    "unix-epoch"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.0.4",
+    "@vitest/coverage-v8": "^1.0.4"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Edge Foundry, Inc.",
+  "license": "Apache-2.0"
+}