timeint2-cli 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,31 @@
1
- # Temporary Holding Version
1
+ # timeint2-cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ English command-line client for the public Timeint2 API.
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ npm install --global timeint2-cli
9
+ ```
10
+
11
+ No account or API key is currently required.
12
+
13
+ ## Use
14
+
15
+ ```sh
16
+ timeint2 time Europe/London
17
+ timeint2 convert 2026-11-18T09:30:00 --from Europe/London --to Asia/Hong_Kong
18
+ timeint2 timezones America --limit 20
19
+ timeint2 time UTC --json
20
+ ```
21
+
22
+ The default API origin is `https://currentlocaltime.co.uk`. Override it for another Timeint2 domain or a development server:
23
+
24
+ ```sh
25
+ timeint2 config set-base-url https://currentlocaltime.co.uk
26
+ TIMEINT2_API_BASE_URL=https://currentlocaltime.co.uk timeint2 time UTC
27
+ ```
28
+
29
+ Configuration is stored in `~/.config/timeint2/config.json` with user-only permissions. Set `TIMEINT2_CONFIG` to use another location.
30
+
31
+ API documentation: <https://currentlocaltime.co.uk/developers/api/>
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env node
2
+
3
+ const { run } = require("../lib/cli");
4
+
5
+ run(process.argv.slice(2)).catch((error) => {
6
+ process.stderr.write(`timeint2: ${error.message}\n`);
7
+ process.exitCode = 1;
8
+ });
package/lib/cli.js ADDED
@@ -0,0 +1,125 @@
1
+ "use strict";
2
+
3
+ const pkg = require("../package.json");
4
+ const messages = require("../locales/en.json");
5
+ const { apiRequest, DEFAULT_BASE_URL, normalizeBaseUrl } = require("./client");
6
+ const { configPath, readConfig, resolveBaseUrl, writeConfig } = require("./config");
7
+
8
+ const HELP = `timeint2 ${pkg.version} — ${messages.description}
9
+
10
+ Usage:
11
+ timeint2 time [timezone] [--json]
12
+ timeint2 convert <datetime> --from <timezone> --to <timezone> [--json]
13
+ timeint2 timezones [query] [--limit <1-200>] [--json]
14
+ timeint2 docs
15
+ timeint2 config get
16
+ timeint2 config set-base-url <url>
17
+ timeint2 config reset
18
+
19
+ Global options:
20
+ --base-url <url> Override the API origin
21
+ --json Print raw JSON
22
+ --help Show this help
23
+ --version Show the version
24
+
25
+ Environment:
26
+ TIMEINT2_API_BASE_URL API origin (default: ${DEFAULT_BASE_URL})
27
+ TIMEINT2_CONFIG Alternate configuration file
28
+ `;
29
+
30
+ function takeOption(args, name) {
31
+ const index = args.indexOf(name);
32
+ if (index === -1) return undefined;
33
+ if (index === args.length - 1) throw new Error(`${name} requires a value`);
34
+ const value = args[index + 1];
35
+ args.splice(index, 2);
36
+ return value;
37
+ }
38
+
39
+ function takeFlag(args, name) {
40
+ const index = args.indexOf(name);
41
+ if (index === -1) return false;
42
+ args.splice(index, 1);
43
+ return true;
44
+ }
45
+
46
+ function printJson(value) {
47
+ process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
48
+ }
49
+
50
+ async function run(inputArgs) {
51
+ const args = [...inputArgs];
52
+ if (!args.length || takeFlag(args, "--help") || takeFlag(args, "-h")) {
53
+ process.stdout.write(HELP);
54
+ return;
55
+ }
56
+ if (takeFlag(args, "--version") || takeFlag(args, "-v")) {
57
+ process.stdout.write(`${pkg.version}\n`);
58
+ return;
59
+ }
60
+ const json = takeFlag(args, "--json");
61
+ const baseUrlOption = takeOption(args, "--base-url");
62
+ const command = args.shift();
63
+
64
+ if (command === "config") {
65
+ const action = args.shift();
66
+ if (action === "get") {
67
+ printJson({ path: configPath(), baseUrl: resolveBaseUrl(baseUrlOption) });
68
+ return;
69
+ }
70
+ if (action === "set-base-url") {
71
+ const value = args.shift();
72
+ if (!value) throw new Error("config set-base-url requires a URL");
73
+ const config = readConfig();
74
+ config.baseUrl = normalizeBaseUrl(value);
75
+ const filename = writeConfig(config);
76
+ process.stdout.write(`Saved ${config.baseUrl} in ${filename}\n`);
77
+ return;
78
+ }
79
+ if (action === "reset") {
80
+ const filename = writeConfig({});
81
+ process.stdout.write(`Reset ${filename}\n`);
82
+ return;
83
+ }
84
+ throw new Error("config requires get, set-base-url, or reset");
85
+ }
86
+
87
+ const baseUrl = resolveBaseUrl(baseUrlOption);
88
+ if (command === "docs") {
89
+ process.stdout.write(`${baseUrl}/developers/api/\n`);
90
+ return;
91
+ }
92
+ if (command === "time") {
93
+ const timezone = args.shift() || "UTC";
94
+ if (args.length) throw new Error(`unexpected argument: ${args[0]}`);
95
+ const result = await apiRequest("/api/v1/time", { timezone }, { baseUrl });
96
+ if (json) return printJson(result);
97
+ process.stdout.write(`${result.local_iso} ${result.timezone} (${result.utc_offset} ${result.abbreviation || ""})\n`);
98
+ return;
99
+ }
100
+ if (command === "convert") {
101
+ const datetime = args.shift();
102
+ const from = takeOption(args, "--from");
103
+ const to = takeOption(args, "--to");
104
+ if (!datetime || !from || !to) {
105
+ throw new Error("convert requires <datetime> --from <timezone> --to <timezone>");
106
+ }
107
+ if (args.length) throw new Error(`unexpected argument: ${args[0]}`);
108
+ const result = await apiRequest("/api/v1/convert", { from, to, datetime }, { baseUrl });
109
+ if (json) return printJson(result);
110
+ process.stdout.write(`${result.source.local_iso} → ${result.target.local_iso}\n`);
111
+ return;
112
+ }
113
+ if (command === "timezones") {
114
+ const limit = takeOption(args, "--limit");
115
+ const query = args.shift() || "";
116
+ if (args.length) throw new Error(`unexpected argument: ${args[0]}`);
117
+ const result = await apiRequest("/api/v1/timezones", { q: query, limit }, { baseUrl });
118
+ if (json) return printJson(result);
119
+ process.stdout.write(`${result.timezones.join("\n")}\n`);
120
+ return;
121
+ }
122
+ throw new Error(`unknown command: ${command}. Run timeint2 --help`);
123
+ }
124
+
125
+ module.exports = { HELP, run, takeFlag, takeOption };
package/lib/client.js ADDED
@@ -0,0 +1,64 @@
1
+ "use strict";
2
+
3
+ const DEFAULT_BASE_URL = "https://currentlocaltime.co.uk";
4
+ const USER_AGENT = "timeint2-cli/0.1.0";
5
+
6
+ class ApiError extends Error {
7
+ constructor(message, status, code) {
8
+ super(message);
9
+ this.name = "ApiError";
10
+ this.status = status;
11
+ this.code = code;
12
+ }
13
+ }
14
+
15
+ function normalizeBaseUrl(value) {
16
+ const url = new URL(value || DEFAULT_BASE_URL);
17
+ if (!/^https?:$/.test(url.protocol)) {
18
+ throw new Error("API base URL must use http or https");
19
+ }
20
+ return url.toString().replace(/\/$/, "");
21
+ }
22
+
23
+ async function apiRequest(path, params = {}, options = {}) {
24
+ const baseUrl = normalizeBaseUrl(options.baseUrl || DEFAULT_BASE_URL);
25
+ const url = new URL(path, `${baseUrl}/`);
26
+ for (const [key, value] of Object.entries(params)) {
27
+ if (value !== undefined && value !== null && value !== "") {
28
+ url.searchParams.set(key, String(value));
29
+ }
30
+ }
31
+ const controller = new AbortController();
32
+ const timeout = setTimeout(() => controller.abort(), options.timeoutMs || 10000);
33
+ let response;
34
+ try {
35
+ response = await fetch(url, {
36
+ headers: { Accept: "application/json", "User-Agent": USER_AGENT },
37
+ signal: controller.signal,
38
+ });
39
+ } catch (error) {
40
+ if (error.name === "AbortError") {
41
+ throw new ApiError(`request timed out after ${options.timeoutMs || 10000}ms`);
42
+ }
43
+ throw new ApiError(`could not reach ${url.origin}: ${error.message}`);
44
+ } finally {
45
+ clearTimeout(timeout);
46
+ }
47
+ let payload;
48
+ try {
49
+ payload = await response.json();
50
+ } catch (_error) {
51
+ throw new ApiError(`API returned non-JSON HTTP ${response.status}`, response.status);
52
+ }
53
+ if (!response.ok) {
54
+ const apiError = payload && payload.error;
55
+ throw new ApiError(
56
+ (apiError && apiError.message) || `API request failed with HTTP ${response.status}`,
57
+ response.status,
58
+ apiError && apiError.code,
59
+ );
60
+ }
61
+ return payload;
62
+ }
63
+
64
+ module.exports = { ApiError, DEFAULT_BASE_URL, apiRequest, normalizeBaseUrl };
package/lib/config.js ADDED
@@ -0,0 +1,37 @@
1
+ "use strict";
2
+
3
+ const fs = require("node:fs");
4
+ const os = require("node:os");
5
+ const path = require("node:path");
6
+ const { DEFAULT_BASE_URL, normalizeBaseUrl } = require("./client");
7
+
8
+ function configPath(env = process.env) {
9
+ if (env.TIMEINT2_CONFIG) return path.resolve(env.TIMEINT2_CONFIG);
10
+ const base = env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
11
+ return path.join(base, "timeint2", "config.json");
12
+ }
13
+
14
+ function readConfig(env = process.env) {
15
+ const filename = configPath(env);
16
+ try {
17
+ return JSON.parse(fs.readFileSync(filename, "utf8"));
18
+ } catch (error) {
19
+ if (error.code === "ENOENT") return {};
20
+ throw new Error(`could not read config ${filename}: ${error.message}`);
21
+ }
22
+ }
23
+
24
+ function writeConfig(config, env = process.env) {
25
+ const filename = configPath(env);
26
+ fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
27
+ fs.writeFileSync(filename, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
28
+ fs.chmodSync(filename, 0o600);
29
+ return filename;
30
+ }
31
+
32
+ function resolveBaseUrl(commandValue, env = process.env) {
33
+ const configured = readConfig(env).baseUrl;
34
+ return normalizeBaseUrl(commandValue || env.TIMEINT2_API_BASE_URL || configured || DEFAULT_BASE_URL);
35
+ }
36
+
37
+ module.exports = { configPath, readConfig, resolveBaseUrl, writeConfig };
@@ -0,0 +1,10 @@
1
+ {
2
+ "description": "Current time and IANA time-zone conversion from your terminal",
3
+ "commands": {
4
+ "time": "Show the current time in an IANA time zone",
5
+ "convert": "Convert an ISO 8601 date-time between IANA time zones",
6
+ "timezones": "Search IANA time-zone identifiers",
7
+ "docs": "Print the API documentation URL",
8
+ "config": "Read or update CLI configuration"
9
+ }
10
+ }
package/package.json CHANGED
@@ -1,6 +1,28 @@
1
1
  {
2
2
  "name": "timeint2-cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Command-line access to the Timeint2 public time-zone API",
5
+ "keywords": [
6
+ "time",
7
+ "timezone",
8
+ "world-clock",
9
+ "cli"
10
+ ],
11
+ "bin": {
12
+ "timeint2": "bin/timeint2.js"
13
+ },
14
+ "files": [
15
+ "bin",
16
+ "lib",
17
+ "locales",
18
+ "README.md"
19
+ ],
20
+ "scripts": {
21
+ "test": "node --test"
22
+ },
23
+ "engines": {
24
+ "node": ">=18"
25
+ },
26
+ "homepage": "https://currentlocaltime.co.uk/developers/api/",
27
+ "license": "UNLICENSED"
28
+ }