Node.js

AbsTime resolves natural language time expressions for AI systems.

Built for agents, assistants, and workflows that need accurate time resolution.

This library provides convenient access to the AbsTime REST API from TypeScript or JavaScript.

Install

npm install @abstime/sdk

Quickstart

import { AbsTime } from "@abstime/sdk";

const client = new AbsTime({ apiKey: process.env.ABSTIME_API_KEY });

const result = await client.resolve({
  text: "the last Friday of this month at 2 pm",
  refTime: "2026-04-09T17:30:00Z",
  refTimezone: "America/Los_Angeles",
});

console.log(result.time);
console.log(result.view);
// 2026-04-24T21:00:00Z
// Apr 24, 2026 2 PM

Core request fields

Use the same request contract shown throughout the docs:

Field	Meaning	Use	Instead of
`text`	Natural language time expression	`two days before Christmas`	`Schedule a meeting with Lily two days before Christmas.`
`refTime`	UTC reference time	`2026-04-09T17:30:00Z`	`2026-04-09T10:30:00-07:00`
`refTimezone`	IANA reference timezone	`America/Los_Angeles`	`PST`

Core result fields

Field	Meaning	Example	Use
`time`	Resolved UTC timestamp	`2026-04-24T21:00:00Z`	Store, compare, or pass to downstream systems
`view`	Human-readable local time	`Apr 24, 2026 2 PM`	Show the result in user interfaces
`confidence`	Resolution confidence signal	`C0`	Guide result presentation and handling

Understand confidence:

C0: a clear resolution; safe to use directly.
C1: less obvious but the most reasonable resolution; still safe to use directly.
C2: sometimes arguable; user confirmation is recommended.

Handling errors

When the library is unable to connect to the API, for example due to a network failure or timeout, an abstime.APIConnectionError is thrown.

When the API returns a non-success status code, a subclass of abstime.AbsTimeError is thrown.

import * as abstime from "@abstime/sdk";

const client = new abstime.AbsTime();

try {
  await client.resolve({
    text: "the last Friday of this month at 2 pm",
    refTime: "2026-04-09T17:30:00Z",
    refTimezone: "America/Los_Angeles",
  });
} catch (err) {
  if (err instanceof abstime.InputError) {
    console.log(`Invalid input: ${err.message}`);
  } else if (err instanceof abstime.RateLimitError) {
    console.log(`Request ID: ${err.requestId}`);
  } else if (err instanceof abstime.APIConnectionError) {
    console.log("The API could not be reached.");
  }
}

Error codes are as follows:

Status Code	Error
`400`	`InputError`
`401`	`AuthenticationError`
`403`	`PermissionDeniedError`
`429`	`RateLimitError`
`>=500`	`InternalError`
`N/A`	`APIConnectionError`

Request IDs

All successful responses provide a requestId from the X-Request-Id response header.

console.log(result.requestId);

For failed requests, catch the error and read err.requestId:

import * as abstime from "@abstime/sdk";

try {
  await client.resolve({
    text: "the last Friday of this month at 2 pm",
    refTime: "2026-04-09T17:30:00Z",
    refTimezone: "America/Los_Angeles",
  });
} catch (err) {
  if (err instanceof abstime.AbsTimeError) {
    console.log(err.requestId);
  }
}

Retries and timeouts

The client retries certain transient failures once by default with a short backoff.

Requests time out after 15 seconds by default.

You can configure both when creating the client.

const client = new AbsTime({
  timeout: 5000,
  maxRetries: 0,
});

Requirements

Node.js 18+