Timestamp Converter AI Integration Guide

{
  "name": "timestamp_convert",
  "description": "Convert between Unix timestamps and human-readable date strings.",
  "parameters": {
    "type": "object",
    "properties": {
      "mode": {
        "type": "string",
        "enum": ["epoch_to_date", "date_to_epoch"]
      },
      "epoch": {
        "type": "number",
        "description": "Unix timestamp in seconds or milliseconds."
      },
      "date_string": {
        "type": "string",
        "description": "ISO-like date string such as 2026-05-17T14:30:00."
      }
    },
    "required": ["mode"]
  }
}

# Task Constraints: Timestamp Converter Module

When converting time values, you MUST be explicit about units and timezone assumptions.

## Core Prohibitions
- NEVER guess whether a timestamp is seconds or milliseconds without documenting the rule.
- NEVER label local time as UTC or vice versa.
- NEVER silently apply natural-language date parsing with ambiguous formats like 05/06/2026.

## Standard Implementation
1. For epoch_to_date, treat absolute values above 1e12 as milliseconds; otherwise treat them as seconds.
2. Return both local display time and UTC display time.
3. For date_to_epoch, require a machine-readable date string and parse it with new Date().
4. If parsing fails, return a validation error instead of fabricating a result.

## Response Requirements
- Always include whether the source epoch was interpreted as seconds or milliseconds.
- Preserve exact integer outputs for both seconds and milliseconds.

function main(args) {
  const { mode, epoch, date_string } = args;

  if (mode === "epoch_to_date") {
    if (typeof epoch !== "number" || Number.isNaN(epoch)) {
      return { success: false, result: null, error: "epoch must be a number" };
    }

    const isMilliseconds = Math.abs(epoch) > 1e12;
    const date = new Date(isMilliseconds ? epoch : epoch * 1000);

    return {
      success: true,
      result: {
        detected_unit: isMilliseconds ? "milliseconds" : "seconds",
        local: date.toLocaleString(),
        utc: date.toISOString().replace("T", " ").replace(/\.\d{3}Z$/, " UTC"),
      },
    };
  }

  if (mode === "date_to_epoch") {
    if (!date_string) {
      return { success: false, result: null, error: "date_string is required" };
    }

    const date = new Date(date_string);
    if (Number.isNaN(date.getTime())) {
      return { success: false, result: null, error: "Invalid date_string" };
    }

    return {
      success: true,
      result: {
        seconds: Math.floor(date.getTime() / 1000),
        milliseconds: date.getTime(),
      },
    };
  }

  return { success: false, result: null, error: "Unknown mode" };
}