ubuyfirst 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 Harvest Mobile. All rights reserved.
+
+You may install and run this software to access the uBuyFirst service through your
+own uBuyFirst account.
+
+You may not copy, modify, distribute, sublicense, sell, or create derivative works
+of this software or any part of it, except where that right cannot be excluded by
+law. No other rights are granted.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# ubuyfirst
+
+Command-line interface for the [uBuyFirst public API](https://app.ubuyfirst.com/api/docs) —
+manage your saved searches, folders, blocklists and notification channels from a terminal or a
+script, and back them up to a file.
+
+Requires Node.js 22.12 or newer.
+
+## Install
+
+```bash
+npx ubuyfirst --help          # run without installing
+npm install -g ubuyfirst      # or install the `ubuyfirst` command
+```
+
+## Get an API key
+
+Generate one on the **Settings → Account** page of your uBuyFirst account. The key is shown
+once, so copy it before leaving the page. There is one key per account; regenerating it
+immediately invalidates the old one.
+
+Store it — the CLI reads the key from stdin so it never lands in your shell history:
+
+```bash
+ubuyfirst config set-key      # paste the key, then press Enter
+ubuyfirst config show         # config path, whether a key is stored, effective base URL
+```
+
+Or pass it per-invocation with the `UBUYFIRST_API_KEY` environment variable, which takes
+precedence over the stored key. `ubuyfirst config clear` removes what is stored.
+
+## Commands
+
+```
+searches       list, create, update, pause, resume, delete, export, import
+folders        list, create, rename, delete, move
+blocklist      list, add, remove          (sellers, countries, items)
+notifications  list, toggle, settings
+filters        export, import
+config         set-key, show, clear
+```
+
+Run `ubuyfirst <group> --help` for the flags of any group.
+
+```bash
+ubuyfirst searches list --limit 20
+ubuyfirst searches create --name "Leica M6" --keywords "leica m6" --price-max 2500
+ubuyfirst searches pause abc123
+ubuyfirst blocklist add --type sellers badseller99 anotherseller
+ubuyfirst searches export > backup.json
+ubuyfirst searches import backup.json --preview
+```
+
+Bulk imports accept `--preview` to report what *would* change without writing anything.
+
+## Scripting
+
+`--json` makes any command — including a failure — emit exactly one parseable JSON document
+on stdout:
+
+```bash
+ubuyfirst --json searches list | jq '.searches[].name'
+```
+
+Exit codes are stable, so a script can branch on the failure without parsing text:
+
+| Code | Meaning | Code | Meaning |
+|---|---|---|---|
+| 0 | success | 6 | ambiguous request |
+| 1 | unexpected failure | 7 | account cap exceeded |
+| 2 | bad or missing flags | 8 | rate limited — back off and retry |
+| 3 | validation error | 9 | write failed |
+| 4 | missing or invalid API key | 10 | server error — retriable |
+| 5 | access denied | 11 | partly applied; see the output |
+
+Codes 8 and 10 are the retriable ones. Client-side refusals also carry a `cli.`-prefixed error
+code in `--json` output (`cli.usage`, `cli.no_key`, `cli.unexpected`) so you can tell them from
+a server response.
+
+## Configuration precedence
+
+| Setting | Order |
+|---|---|
+| API key | `UBUYFIRST_API_KEY` → stored config |
+| Base URL | `--base-url` → `UBUYFIRST_API_URL` → stored config → `https://app.ubuyfirst.com` |
+
+## Licence
+
+Proprietary — see [LICENSE](./LICENSE). You may install and run this software to access the
+uBuyFirst service through your own account.

package/dist/cli.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+//#region src/node-floor.ts
+/**
+* The CLI's RUNTIME floor is Node >=22.12.0 — Commander 15's own minimum
+* (verified at the npm registry). This is distinct from, and lower than, the
+* BUILD floor (`devEngines.runtime` in package.json, `^22.18.0 || ^24.11.0 ||
+* >=26.0.0` — tsdown's own floor). Never collapse the two into one number.
+*
+* npm's `engines` field only WARNS unless the consumer sets `engine-strict`,
+* so the built entry (`cli.ts`) performs this check itself, before anything
+* else runs, and exits with a message naming both versions.
+*/
+const REQUIRED_NODE_VERSION = "22.12.0";
+/**
+* Strips a leading `v` (as in `process.version`) and any pre-release /
+* build-metadata suffix (`-nightly...`, `+build...`), then parses the
+* remaining `major.minor.patch` core. A missing or non-numeric segment
+* parses as 0 rather than throwing.
+*/
+function parseVersion(raw) {
+	const segments = (raw.replace(/^v/, "").split(/[-+]/)[0] ?? "").split(".");
+	const toNumber = (segment) => {
+		const value = Number(segment ?? "0");
+		return Number.isNaN(value) ? 0 : value;
+	};
+	return {
+		major: toNumber(segments[0]),
+		minor: toNumber(segments[1]),
+		patch: toNumber(segments[2])
+	};
+}
+function compareVersions(a, b) {
+	if (a.major !== b.major) return a.major - b.major;
+	if (a.minor !== b.minor) return a.minor - b.minor;
+	return a.patch - b.patch;
+}
+/**
+* Checks `runningVersion` (defaults to `process.version`) against
+* `REQUIRED_NODE_VERSION`. Pure and injectable so it is testable without
+* switching Node binaries — the caller decides how to report a failure.
+*/
+function checkNodeFloor(runningVersion = process.version) {
+	if (compareVersions(parseVersion(runningVersion), parseVersion("22.12.0")) < 0) return {
+		ok: false,
+		message: `ubuyfirst requires Node.js >=${REQUIRED_NODE_VERSION}; the running version is ${runningVersion}.`
+	};
+	return {
+		ok: true,
+		message: ""
+	};
+}
+//#endregion
+//#region src/cli.ts
+const floorCheck = checkNodeFloor(process.version);
+if (!floorCheck.ok) {
+	process.stderr.write(`${floorCheck.message}\n`);
+	process.exitCode = 1;
+} else {
+	const { runProgram } = await import("./program-YTm6g9Ut.js");
+	await runProgram(process.argv.slice(2));
+}
+//#endregion
+export {};