API Documentation

Scenario 1: Scheduling a meeting during a DST gap

A user in New York picks March 8, 2026 at 2:30 AM for a standup. That time will never exist — clocks jump from 2:00 AM to 3:00 AM.

Scenario 2: Cron job during a fall-back overlap

A billing job runs at 1:30 AM on November 1, 2026 in New York. Clocks fall back, so 1:30 AM happens twice — once at UTC-4 and again at UTC-5.

When: A user picks a date+time in your UI (booking form, scheduler, "remind me at...") and you're about to write it to the database.

Where in your app: Inside the request handler that receives the form submission, BEFORE the INSERT.

// Pseudocode — Express/Fastify/etc. handler
app.post("/bookings", async (req, res) => {
  const { local_datetime, time_zone } = req.body;

  const check = await chronoshield.validate({ local_datetime, time_zone });
  if (check.status !== "valid") {
    return res.status(400).json({
      error: "Invalid time",
      reason: check.reason_code,
      suggested_fixes: check.suggested_fixes,
    });
  }

  // Safe to store. Resolve to UTC and persist.
  const utc = await chronoshield.resolve({ local_datetime, time_zone });
  await db.bookings.create({ instant_utc: utc.instant_utc, local_datetime, time_zone });
});

When: User says "run this every day at 9am Eastern." Your job runner needs a UTC timestamp to fire on.

Where in your app: When computing the next fire time for a recurring job. Recompute after each run — don't add 24h to the previous fire (DST drifts that).

// After each run, compute the next fire time fresh
async function nextFire(localTime, tz) {
  const tomorrow = addDays(localToday(tz), 1);
  const localDt = `${tomorrow}T${localTime}`;

  const resolved = await chronoshield.resolve({
    local_datetime: localDt,
    time_zone: tz,
    resolution_policy: { invalid: "next_valid_time", ambiguous: "earlier" },
  });
  return resolved.instant_utc;
}

When: Always — this is the schema you should use for any time-bound record.

Why all three: UTC is for sorting/triggering; local + tz is for re-rendering and re-resolving if tzdb rules change after storage.

-- PostgreSQL example
CREATE TABLE bookings (
  id UUID PRIMARY KEY,
  instant_utc      TIMESTAMPTZ NOT NULL,   -- for indexing, sorting, scheduling
  local_datetime   TEXT NOT NULL,          -- original user input
  time_zone        TEXT NOT NULL,          -- IANA zone they picked in
  ...
);
CREATE INDEX ON bookings (instant_utc);

Storing only UTC means you lose the user's intent if a tzdb rule changes (e.g. a country abolishes DST). Keeping all three lets you re-resolve cleanly.

When: The local time the user picked doesn't exist (spring-forward).

UI pattern: Render suggested_fixes[0].local_datetime as a "did you mean?" prompt. Don't silently shift — the user picked that time for a reason; let them confirm or pick differently.

if (result.reason_code === "DST_GAP") {
  showModal({
    title: "That time doesn't exist on this day",
    body: `Clocks jump from 02:00 to 03:00 for daylight saving. Want to use ${result.suggested_fixes[0].local_datetime} instead?`,
    actions: [
      { label: "Use 3:00 AM", onClick: () => submit(result.suggested_fixes[0].local_datetime) },
      { label: "Pick another time", onClick: () => reopenPicker() },
    ],
  });
}

When: The local time happens twice (fall-back). Two valid UTC instants exist; you have to pick one.

Recommended defaults by use case:

• Calendar / scheduling: earlier — the user means "the first time 1:30 AM happens that day"
• Billing / cron: earlier + idempotent job design — cheaper than charging twice
• High-stakes / financial: reject — force the caller to ask the user

const resolved = await chronoshield.resolve({
  local_datetime, time_zone,
  resolution_policy: {
    ambiguous: "earlier",        // or "later" / "reject"
    invalid: "next_valid_time",  // or "previous_valid_time" / "reject"
  },
});

When: Importing a calendar (.ics), processing a CSV of recurring events, or an LLM has generated a list of times to schedule.

Why batch: One round-trip vs. N. The batch endpoint isolates per-item failures so a single invalid time doesn't fail the whole import.

const result = await chronoshield.batch({
  items: scheduleItems.map(item => ({
    operation: "validate",
    local_datetime: item.start,
    time_zone: item.tz,
  })),
});

const invalid = result.results.filter(r => !r.success || r.data.status !== "valid");
if (invalid.length) {
  presentImportReview(invalid);  // let user fix bad rows before commit
}