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 +30 -2
- package/bin/timeint2.js +8 -0
- package/lib/cli.js +125 -0
- package/lib/client.js +64 -0
- package/lib/config.js +37 -0
- package/locales/en.json +10 -0
- package/package.json +26 -4
package/README.md
CHANGED
|
@@ -1,3 +1,31 @@
|
|
|
1
|
-
#
|
|
1
|
+
# timeint2-cli
|
|
2
2
|
|
|
3
|
-
|
|
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/>
|
package/bin/timeint2.js
ADDED
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 };
|
package/locales/en.json
ADDED
|
@@ -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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|