@surelycrm/cli 1.0.0

package/README.md

@@ -0,0 +1,67 @@
+# @surelycrm/cli
+
+A command-line interface for the SurelyCrm API.
+
+## Requirements
+
+- Node.js 18 or later
+- A SurelyCrm API key (from **Settings > Application Settings**)
+
+## Installation
+
+Install globally from npm:
+
+```bash
+npm install -g @surelycrm/cli
+```
+
+Or run without installing:
+
+```bash
+npx @surelycrm/cli --help
+```
+
+To develop locally, clone the repo and link the package:
+
+```bash
+cd Sure.Cli
+npm install
+npm link
+```
+
+## Usage
+
+### Initialise
+
+```bash
+sure-cli init --url https://app.surelycrm.co.uk/ --api-key {your-api-key}
+```
+
+Configuration is stored in `~/.surecli/config.json`.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `sure-cli config` | Show stored configuration |
+| `sure-cli create-customer` | Create a new customer |
+| `sure-cli get-customer --id {guid}` | Get a customer by GUID |
+| `sure-cli get-customer-by-reference --reference {ref}` | Get a customer by reference number |
+| `sure-cli update-customer --id {guid}` | Update an existing customer |
+| `sure-cli change-status --customer-id {guid} --status-id {guid}` | Change a customer's status |
+| `sure-cli start-workflow --customer-id {guid} --workflow-name {name}` | Start a workflow for a customer |
+| `sure-cli get-customers-by-age --age {age} --comparison {comparison}` | Filter customers by age |
+
+Use `--help` on any command for details.
+
+### Templates
+
+JSON templates for complex payloads are in the `templates/` directory:
+
+- `customer.json` — customer create/update payload
+- `status-change.json` — status change payload
+- `workflow-start.json` — workflow start payload
+
+## Documentation
+
+See `guid/cli.html` for the full CLI reference guide.

package/bin/sure-cli.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const fs = require('fs');
+const path = require('path');
+const { loadConfig, saveConfig, requireConfig } = require('../lib/config');
+const { request, handleResponse } = require('../lib/api');
+
+const program = new Command();
+program.name('sure-cli').description('CLI wrapper for the SurelyCrm API').version('1.0.0');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+function loadTemplate(name) {
+    const filePath = path.join(TEMPLATES_DIR, `${name}.json`);
+    if (!fs.existsSync(filePath)) {
+        console.error(`Template not found: ${filePath}`);
+        process.exit(1);
+    }
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch (err) {
+        console.error(`Failed to parse template ${filePath}: ${err.message}`);
+        process.exit(1);
+    }
+}
+
+function parseDataInput(options) {
+    if (options.data) {
+        try {
+            return JSON.parse(options.data);
+        } catch (err) {
+            console.error(`Failed to parse inline JSON: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    if (options.template) {
+        try {
+            return JSON.parse(fs.readFileSync(options.template, 'utf8'));
+        } catch (err) {
+            console.error(`Failed to read template file: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    return null;
+}
+
+function getRequiredOption(options, name) {
+    const value = options[name];
+    if (!value) {
+        console.error(`Missing required option: --${name}`);
+        process.exit(1);
+    }
+    return value;
+}
+
+function run(action) {
+    return async (...args) => {
+        try {
+            await action(...args);
+        } catch (err) {
+            if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT') {
+                console.error(`Unable to connect to the API: ${err.message || err.code}`);
+            } else if (err.message) {
+                console.error(err.message);
+            } else {
+                console.error(err);
+            }
+            process.exit(1);
+        }
+    };
+}
+
+program
+    .command('init')
+    .description('Initialise the CLI with the API base URL and API key')
+    .requiredOption('--url <url>', 'Base URL of the SurelyCrm API (e.g. https://app.surelycrm.co.uk/)')
+    .requiredOption('--api-key <key>', 'API key GUID')
+    .action((options) => {
+        const baseUrl = options.url.endsWith('/') ? options.url : `${options.url}/`;
+        saveConfig({ baseUrl, apiKey: options.apiKey });
+        console.log('Configuration saved.');
+    });
+
+program
+    .command('config')
+    .description('Show the current configuration')
+    .action(() => {
+        const config = requireConfig();
+        console.log(JSON.stringify(config, null, 2));
+    });
+
+program
+    .command('create-customer')
+    .description('Create a new customer')
+    .option('--template <file>', 'Path to a JSON customer template')
+    .option('--data <json>', 'Inline JSON customer payload')
+    .action(run(async (options) => {
+        const config = requireConfig();
+        let body = parseDataInput(options);
+        if (!body) {
+            body = loadTemplate('customer');
+        }
+        const response = await request(config.baseUrl, config.apiKey, 'POST', 'Api/Create', body);
+        handleResponse(response);
+    }));
+
+program
+    .command('get-customer')
+    .description('Get a customer by GUID')
+    .requiredOption('--id <guid>', 'Customer GUID')
+    .action(run(async (options) => {
+        const config = requireConfig();
+        const id = getRequiredOption(options, 'id');
+        const response = await request(config.baseUrl, config.apiKey, 'GET', `Api/customer/${id}`);
+        handleResponse(response);
+    }));
+
+program
+    .command('get-customer-by-reference')
+    .description('Get a customer by reference number')
+    .requiredOption('--reference <reference>', 'Customer reference number')
+    .action(run(async (options) => {
+        const config = requireConfig();
+        const reference = getRequiredOption(options, 'reference');
+        const response = await request(config.baseUrl, config.apiKey, 'GET', `Api/customer/reference/${encodeURIComponent(reference)}`);
+        handleResponse(response);
+    }));
+
+program
+    .command('update-customer')
+    .description('Update an existing customer')
+    .requiredOption('--id <guid>', 'Customer GUID')
+    .option('--template <file>', 'Path to a JSON customer template')
+    .option('--data <json>', 'Inline JSON customer payload')
+    .action(run(async (options) => {
+        const config = requireConfig();
+        const id = getRequiredOption(options, 'id');
+        let body = parseDataInput(options);
+        if (!body) {
+            body = loadTemplate('customer');
+        }
+        body.id = id;
+        const response = await request(config.baseUrl, config.apiKey, 'PUT', `Api/customer/${id}`, body);
+        handleResponse(response);
+    }));
+
+program
+    .command('change-status')
+    .description('Change a customer account status')
+    .requiredOption('--customer-id <guid>', 'Customer GUID')
+    .requiredOption('--status-id <guid>', 'Status GUID')
+    .action(run(async (options) => {
+        const config = requireConfig();
+        const customerId = getRequiredOption(options, 'customerId');
+        const statusId = getRequiredOption(options, 'statusId');
+        const body = { statusId };
+        const response = await request(config.baseUrl, config.apiKey, 'POST', `Api/customer/${customerId}/status`, body);
+        handleResponse(response);
+    }));
+
+program
+    .command('start-workflow')
+    .description('Start a workflow for a customer')
+    .requiredOption('--customer-id <guid>', 'Customer GUID')
+    .option('--workflow-id <guid>', 'Workflow GUID')
+    .option('--workflow-name <name>', 'Workflow name')
+    .option('--context-data <json>', 'JSON context data for the workflow instance', '{}')
+    .action(run(async (options) => {
+        const config = requireConfig();
+        const customerId = getRequiredOption(options, 'customerId');
+
+        if (!options.workflowId && !options.workflowName) {
+            console.error('Either --workflow-id or --workflow-name is required');
+            process.exit(1);
+        }
+
+        const body = {
+            customerId,
+            contextData: options.contextData
+        };
+        if (options.workflowId) body.workflowId = options.workflowId;
+        if (options.workflowName) body.workflowName = options.workflowName;
+
+        const response = await request(config.baseUrl, config.apiKey, 'POST', `Api/customer/${customerId}/workflow`, body);
+        handleResponse(response);
+    }));
+
+program
+    .command('get-customers-by-age')
+    .description('Get customers filtered by age')
+    .requiredOption('--age <age>', 'Age value', parseInt)
+    .option('--comparison <comparison>', 'Comparison operator (equal, greater, less, greaterthanorequal, lessthanorequal)', 'equal')
+    .action(run(async (options) => {
+        const config = requireConfig();
+        const age = getRequiredOption(options, 'age');
+        const comparison = options.comparison;
+        const response = await request(config.baseUrl, config.apiKey, 'GET', `Api/customers/byAge?age=${age}&comparison=${encodeURIComponent(comparison)}`);
+        handleResponse(response);
+    }));
+
+program.parse();

package/lib/api.js

@@ -0,0 +1,68 @@
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+function request(baseUrl, apiKey, method, path, body = null) {
+    return new Promise((resolve, reject) => {
+        const url = new URL(path, baseUrl);
+        const transport = url.protocol === 'https:' ? https : http;
+
+        const options = {
+            hostname: url.hostname,
+            port: url.port,
+            path: url.pathname + url.search,
+            method: method.toUpperCase(),
+            headers: {
+                'apiKey': apiKey,
+                'Accept': 'application/json'
+            }
+        };
+
+        let payload = null;
+        if (body) {
+            payload = JSON.stringify(body);
+            options.headers['Content-Type'] = 'application/json';
+            options.headers['Content-Length'] = Buffer.byteLength(payload);
+        }
+
+        const req = transport.request(options, (res) => {
+            let data = '';
+            res.on('data', (chunk) => {
+                data += chunk;
+            });
+            res.on('end', () => {
+                try {
+                    const parsed = data ? JSON.parse(data) : null;
+                    resolve({ status: res.statusCode, data: parsed, raw: data });
+                } catch {
+                    resolve({ status: res.statusCode, data: data, raw: data });
+                }
+            });
+        });
+
+        req.on('error', (err) => {
+            reject(err);
+        });
+
+        if (payload) {
+            req.write(payload);
+        }
+        req.end();
+    });
+}
+
+function handleResponse(response) {
+    const output = JSON.stringify(response.data, null, 2);
+    if (response.status >= 200 && response.status < 300) {
+        console.log(output);
+    } else {
+        console.error(`HTTP ${response.status}`);
+        console.error(output);
+        process.exit(1);
+    }
+}
+
+module.exports = {
+    request,
+    handleResponse
+};

package/lib/config.js

@@ -0,0 +1,51 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CONFIG_DIR = path.join(os.homedir(), '.surecli');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+function ensureConfigDir() {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+}
+
+function loadConfig() {
+    ensureConfigDir();
+    if (!fs.existsSync(CONFIG_FILE)) {
+        return null;
+    }
+    try {
+        return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    } catch (err) {
+        console.error('Error reading config file:', err.message);
+        process.exit(1);
+    }
+}
+
+function saveConfig(config) {
+    ensureConfigDir();
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+function requireConfig() {
+    const config = loadConfig();
+    if (!config) {
+        console.error('Configuration not found. Run: sure-cli init');
+        process.exit(1);
+    }
+    if (!config.baseUrl || !config.apiKey) {
+        console.error('Configuration is incomplete. Run: sure-cli init');
+        process.exit(1);
+    }
+    return config;
+}
+
+module.exports = {
+    CONFIG_DIR,
+    CONFIG_FILE,
+    loadConfig,
+    saveConfig,
+    requireConfig
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@surelycrm/cli",
+  "version": "1.0.0",
+  "description": "CLI wrapper for the SurelyCrm API",
+  "main": "index.js",
+  "bin": {
+    "sure-cli": "./bin/sure-cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node bin/sure-cli.js --help"
+  },
+  "keywords": [
+    "surelycrm",
+    "cli",
+    "api"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/templates/customer.json

@@ -0,0 +1,24 @@
+{
+  "title": "Mr",
+  "firstname": "John",
+  "surname": "Davies",
+  "referenceNumber": "",
+  "address1": "123 High Street",
+  "address2": "",
+  "address3": "",
+  "address4": "",
+  "town": "Manchester",
+  "city": "Greater Manchester",
+  "postcode": "M1 1AA",
+  "homePhone": "",
+  "mobilePhone": "07700900123",
+  "emailAddress": "john.davies@example.com",
+  "notificationsEnabled": true,
+  "importantDate": null,
+  "dateOfBirth": null,
+  "website": "",
+  "statusId": null,
+  "ownerId": null,
+  "referredBy": "",
+  "customFields": {}
+}

package/templates/status-change.json

@@ -0,0 +1,3 @@
+{
+  "statusId": "00000000-0000-0000-0000-000000000000"
+}

package/templates/workflow-start.json

@@ -0,0 +1,5 @@
+{
+  "workflowId": "00000000-0000-0000-0000-000000000000",
+  "workflowName": "",
+  "contextData": "{}"
+}