@uqpay/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UQPAY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR COPYRIGHT HOLDERS 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,207 @@
+# uqpay-cli
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Go Version](https://img.shields.io/badge/go-%3E%3D1.21-blue.svg)](https://go.dev/)
+[![npm version](https://img.shields.io/npm/v/@uqpay/cli.svg)](https://www.npmjs.com/package/@uqpay/cli)
+
+The official [UQPAY](https://www.uqpay.com/) CLI tool — built for humans and AI Agents. Covers Banking, Card Issuing, and Payment APIs with 100+ commands and 6 AI Agent [Skills](./skills/).
+
+[Install](#installation) · [Quick Start](#quick-start) · [AI Agent Skills](#agent-skills) · [Commands](#command-structure) · [Advanced](#advanced-usage) · [Contributing](#contributing)
+
+## Why uqpay-cli?
+
+- **Agent-Native Design** — 6 structured [Skills](./skills/) out of the box, AI Agents can operate UQPAY APIs with zero extra setup
+- **Wide Coverage** — 3 business domains (Banking, Issuing, Payment), 100+ commands, Connect & Simulator included
+- **Zero Type Hassle** — All values default to strings, number fields auto-converted per API spec — just type `-d amount=100` and it works
+- **Open Source** — MIT license, `npm install` and go
+- **Up and Running in 1 Minute** — Set credentials, start calling APIs
+- **Cross-Platform** — macOS, Linux, Windows (amd64 & arm64)
+
+## Features
+
+| Domain | Capabilities |
+|--------|-------------|
+| 🏦 Banking | Balances, transfers, deposits, payouts, beneficiaries, FX conversions, exchange rates, virtual accounts |
+| 💳 Issuing | Card products, cardholders, virtual/physical cards, recharge/withdraw, transactions, spending controls, reports |
+| 💰 Payment | Payment intents, attempts, refunds, settlements, bank accounts, payouts |
+| 🔗 Connect | Connected accounts, sub-account onboarding (COMPANY/INDIVIDUAL), KYC document upload |
+| 🧪 Simulator | Sandbox-only: simulate deposits, card authorizations, reversals |
+| 📁 File | Upload files, get download links |
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+npm install -g @uqpay/cli
+```
+
+### From source
+
+Requires Go 1.21+.
+
+```bash
+git clone https://github.com/uqpay/uqpay-cli.git
+cd uqpay-cli
+make install
+```
+
+### Enable tab completion (optional)
+
+```bash
+uqpay setup-completion
+source ~/.zshrc  # or ~/.bashrc
+```
+
+## Quick Start
+
+```bash
+# 1. Configure credentials (one-time)
+uqpay config set client-id YOUR_CLIENT_ID
+uqpay config set api-key YOUR_API_KEY
+uqpay config set env sandbox
+
+# 2. Start using
+uqpay banking balance list
+uqpay issuing card list
+uqpay payment intent list
+```
+
+Or inline without config file:
+
+```bash
+uqpay --env sandbox --client-id ID --api-key KEY banking balance list
+```
+
+## Quick Start (AI Agent)
+
+```bash
+# Step 1 — Install
+npm install -g @uqpay/cli
+
+# Step 2 — Configure (provide credentials from UQPAY dashboard)
+uqpay config set client-id <CLIENT_ID>
+uqpay config set api-key <API_KEY>
+uqpay config set env sandbox
+
+# Step 3 — Verify
+uqpay banking balance list
+```
+
+## Agent Skills
+
+Located in [`skills/`](./skills/), these provide structured guides for AI Agents to operate UQPAY APIs correctly.
+
+| Skill | Description |
+|-------|-------------|
+| [`uqpay-shared`](./skills/uqpay-shared/SKILL.md) | Configuration, authentication, global flags, data conventions, auto number coercion |
+| [`uqpay-banking`](./skills/uqpay-banking/SKILL.md) | Balances, beneficiaries, payouts, conversions, transfers, deposits, virtual accounts |
+| [`uqpay-issuing`](./skills/uqpay-issuing/SKILL.md) | Cards, cardholders, products, transactions, transfers, reports |
+| [`uqpay-payment`](./skills/uqpay-payment/SKILL.md) | Payment intents, attempts, refunds, settlements, bank accounts, payouts |
+| [`uqpay-connect`](./skills/uqpay-connect/SKILL.md) | Connected accounts, sub-account onboarding, `--on-behalf-of` operations |
+| [`uqpay-simulate`](./skills/uqpay-simulate/SKILL.md) | Sandbox testing: deposits, authorizations, reversals |
+
+## Command Structure
+
+```
+uqpay <domain> <resource> <action> [flags]
+```
+
+### Domains
+
+```bash
+uqpay banking balance list           # Banking API
+uqpay issuing card list              # Issuing API
+uqpay payment intent list            # Payment API
+```
+
+### Other Commands
+
+```bash
+uqpay account list                   # Connected accounts (Connect API)
+uqpay config get                     # CLI configuration
+uqpay file upload ./doc.pdf          # File upload
+uqpay simulate deposit -d ...        # Sandbox simulator
+uqpay setup-completion               # Install shell tab-completion
+```
+
+### Shortcuts
+
+Top-level aliases for common resources:
+
+```bash
+uqpay beneficiary list               # = uqpay banking beneficiary list
+uqpay card list                      # = uqpay issuing card list
+uqpay payout list                    # = uqpay banking payout list
+uqpay conversion list                # = uqpay banking conversion list
+uqpay cardholder list                # = uqpay issuing cardholder list
+uqpay exchange-rate list             # = uqpay banking exchange-rate list
+```
+
+## Data Passing
+
+**Read operations** use flags, **write operations** use `-d key=value`:
+
+```bash
+# Read (GET)
+uqpay banking beneficiary list --page-num 2 --page-size 20
+
+# Write (POST) — dot notation for nested objects
+uqpay banking beneficiary create \
+  -d entity_type=INDIVIDUAL \
+  -d first_name=John \
+  -d last_name=Doe \
+  -d bank_details.swift_code=DBSSSGSG \
+  -d bank_details.account_number=1234567890
+```
+
+All values are strings by default. Number fields (like `amount` in card recharge) are auto-converted — no prefix needed.
+
+## Advanced Usage
+
+### Output Formats
+
+```bash
+uqpay banking balance list              # table (default)
+uqpay banking balance list -o json      # JSON
+uqpay banking balance list -o yaml      # YAML
+```
+
+### Debug Mode
+
+```bash
+uqpay --debug banking balance list      # Print HTTP request/response details
+```
+
+### Sub-Account Operations
+
+```bash
+uqpay --on-behalf-of <account-id> banking balance list
+```
+
+### File Encoding
+
+```bash
+# Pure base64 (issuing identity documents)
+-d identity.front_file=@./passport.jpg
+
+# Data URI (connect account documents)
+-d "certification[0]=@+./cert.png"
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `UQPAY_CLIENT_ID` | Override client ID |
+| `UQPAY_API_KEY` | Override API key |
+| `UQPAY_ENV` | Override environment (sandbox/production) |
+| `UQPAY_OUTPUT` | Override output format |
+
+## Contributing
+
+Contributions welcome! Please submit an [Issue](https://github.com/uqpay/uqpay-cli/issues) or [Pull Request](https://github.com/uqpay/uqpay-cli/pulls).
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@uqpay/cli",
+  "version": "0.1.0",
+  "description": "UQPAY command-line tool for banking, issuing, and payment APIs",
+  "bin": {
+    "uqpay": "scripts/run.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uqpay/uqpay-cli.git"
+  },
+  "license": "MIT",
+  "files": [
+    "scripts/install.js",
+    "scripts/run.js"
+  ]
+}

package/scripts/install.js

@@ -0,0 +1,88 @@
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const os = require("os");
+
+const VERSION = require("../package.json").version;
+const REPO = "uqpay/uqpay-cli";
+const NAME = "uqpay";
+
+const PLATFORM_MAP = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+};
+
+const ARCH_MAP = {
+  x64: "amd64",
+  arm64: "arm64",
+};
+
+const platform = PLATFORM_MAP[process.platform];
+const arch = ARCH_MAP[process.arch];
+
+if (!platform || !arch) {
+  console.error(
+    `Unsupported platform: ${process.platform}-${process.arch}`
+  );
+  process.exit(1);
+}
+
+const isWindows = process.platform === "win32";
+const ext = isWindows ? ".zip" : ".tar.gz";
+const archiveName = `${NAME}-${VERSION}-${platform}-${arch}${ext}`;
+const GITHUB_URL = `https://github.com/${REPO}/releases/download/v${VERSION}/${archiveName}`;
+
+const binDir = path.join(__dirname, "..", "bin");
+const dest = path.join(binDir, NAME + (isWindows ? ".exe" : ""));
+
+fs.mkdirSync(binDir, { recursive: true });
+
+function download(url, destPath) {
+  const sslFlag = isWindows ? "--ssl-revoke-best-effort " : "";
+  execSync(
+    `curl ${sslFlag}--fail --location --silent --show-error --connect-timeout 10 --max-time 120 --output "${destPath}" "${url}"`,
+    { stdio: ["ignore", "ignore", "pipe"] }
+  );
+}
+
+function install() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "uqpay-cli-"));
+  const archivePath = path.join(tmpDir, archiveName);
+
+  try {
+    download(GITHUB_URL, archivePath);
+
+    if (isWindows) {
+      execSync(
+        `powershell -Command "Expand-Archive -Path '${archivePath}' -DestinationPath '${tmpDir}'"`,
+        { stdio: "ignore" }
+      );
+    } else {
+      execSync(`tar -xzf "${archivePath}" -C "${tmpDir}"`, {
+        stdio: "ignore",
+      });
+    }
+
+    const binaryName = NAME + (isWindows ? ".exe" : "");
+    const extractedBinary = path.join(tmpDir, binaryName);
+
+    fs.copyFileSync(extractedBinary, dest);
+    fs.chmodSync(dest, 0o755);
+    console.log(`${NAME} v${VERSION} installed successfully`);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+try {
+  install();
+} catch (err) {
+  console.error(`Failed to install ${NAME}:`, err.message);
+  console.error(
+    `\nIf you are behind a firewall, try setting a proxy:\n` +
+    `  export https_proxy=http://your-proxy:port\n` +
+    `  npm install -g @uqpay/cli`
+  );
+  process.exit(1);
+}

package/scripts/run.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+const { execFileSync } = require("child_process");
+const path = require("path");
+
+const ext = process.platform === "win32" ? ".exe" : "";
+const bin = path.join(__dirname, "..", "bin", "uqpay" + ext);
+
+try {
+  execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
+} catch (e) {
+  process.exit(e.status || 1);
+}