@thinremote/thinr-cli 1.0.2-alpha.2 → 1.1.0-alpha.1

package/lib/proxy.js

@@ -1,8 +1,9 @@
 import chalk from 'chalk';
 import open, { apps } from 'open';
 import ora from 'ora';
-import { configExists, readConfig } from './config.js';
+import { readConfig, requireConfig } from './config.js';
 import api from './api.js';
+import { apiError } from './errors.js';
 
 /**
  * Parse target argument into address and port
@@ -75,49 +76,43 @@ function parseTarget(target, defaultPort) {
     return {
         address: address || 'localhost',
         port: port,
-        isSecure
+        isSecure,
     };
 }
 
 /**
- * Create proxy action handler
+ * Open a proxy and keep it running until the user hits Ctrl+C.
+ * Resolves with `0` on a clean SIGINT shutdown, rejects with the
+ * underlying error if the proxy can't be created. Never calls
+ * process.exit — the wrapping CLI command decides what to do with
+ * the resolved code or the thrown error.
+ *
+ * @returns {Promise<number>} Exit code (0 on clean shutdown)
  */
 export async function handleProxyAction(deviceId, protocol, target, options) {
-    // Check if configured
-    if (!configExists()) {
-        console.error(chalk.red('Error: Not configured. Run thinr without parameters to set up.'));
-        process.exit(1);
-    }
-
-    // Determine default port based on protocol
-    const defaultPort = protocol === 'http' ? 80 : (protocol === 'tls' ? 443 : 22);
+    const defaultPort = protocol === 'http' ? 80 : protocol === 'tls' ? 443 : 22;
     const { address, port, isSecure } = parseTarget(target, defaultPort);
 
-    // Determine proxy configuration based on protocol
-    let proxyConfig = {
+    const proxyConfig = {
         targetAddress: address,
         targetPort: port,
         serverPort: options.port ? parseInt(options.port) : null,
         targetSecure: false,
         serverSecure: false,
-        web: false
+        web: false,
     };
 
     switch (protocol) {
         case 'tcp':
-            // TCP proxy without TLS
             proxyConfig.serverSecure = false;
             break;
         case 'tls':
-            // TLS proxy
             proxyConfig.targetSecure = true;
             proxyConfig.serverSecure = true;
             break;
         case 'http':
-            // HTTP proxy
             proxyConfig.web = true;
-            proxyConfig.serverSecure = true; // Default to HTTPS for web interface
-            // Use the isSecure flag from parseTarget
+            proxyConfig.serverSecure = true;
             proxyConfig.targetSecure = isSecure || port === 443;
             break;
     }
@@ -125,54 +120,44 @@ export async function handleProxyAction(deviceId, protocol, target, options) {
     const proxyType = proxyConfig.web ? 'HTTP proxy' : `${protocol.toUpperCase()} proxy`;
     const spinner = ora(`Creating ${proxyType} to ${deviceId} (${address}:${port})...`).start();
     let proxyId = null;
+    let proxy;
 
     try {
-        // Create proxy
-        const proxy = await createProxy(deviceId, proxyConfig);
+        proxy = await createProxy(deviceId, proxyConfig);
         proxyId = proxy.proxyId;
+    } catch (error) {
+        spinner.fail(`Failed to create ${proxyType}`);
+        if (proxyId) await deleteProxy(proxyId);
+        throw error;
+    }
 
-        if (proxyConfig.web) {
-            // For HTTP proxy, show target as URL format
-            const targetProtocol = isSecure ? 'https' : 'http';
-            const targetUrl = `${targetProtocol}://${address}${port === 80 || port === 443 ? '' : `:${port}`}`;
-
-            spinner.succeed(`HTTP proxy running at ${chalk.blue(proxy.url)} → ${deviceId} -> ${chalk.cyan(targetUrl)}`);
-
-            // Open browser if not disabled
-            if (options.openBrowser !== false) {
-                await openBrowser(proxy.url);
-            }
-        } else {
-            // For TCP/TLS proxy, show address:port format
-            const secureInfo = isSecure ? ' [TLS]' : '';
-            spinner.succeed(`${protocol.toUpperCase()} proxy running on ${chalk.blue(proxy.serverHost + ':' + proxy.serverPort)} → ${deviceId} (${address}:${port})${secureInfo}`);
+    if (proxyConfig.web) {
+        const targetProtocol = isSecure ? 'https' : 'http';
+        const targetUrl = `${targetProtocol}://${address}${port === 80 || port === 443 ? '' : `:${port}`}`;
+        spinner.succeed(
+            `HTTP proxy running at ${chalk.blue(proxy.url)} → ${deviceId} -> ${chalk.cyan(targetUrl)}`,
+        );
+        if (options.openBrowser !== false) {
+            await openBrowser(proxy.url);
         }
+    } else {
+        const secureInfo = isSecure ? ' [TLS]' : '';
+        spinner.succeed(
+            `${protocol.toUpperCase()} proxy running on ${chalk.blue(proxy.serverHost + ':' + proxy.serverPort)} → ${deviceId} (${address}:${port})${secureInfo}`,
+        );
+    }
 
-        console.log(chalk.gray(`Press Ctrl+C to stop`));
+    console.log(chalk.gray(`Press Ctrl+C to stop`));
+    process.stdin.resume();
 
-        // Handle process termination
+    // Resolve when the user hits Ctrl+C — the CLI command then exits cleanly.
+    return new Promise((resolve) => {
         process.on('SIGINT', async () => {
             console.log(chalk.yellow('\nStopping proxy...'));
-            if (proxyId) {
-                await deleteProxy(proxyId);
-            }
-            process.exit(0);
+            if (proxyId) await deleteProxy(proxyId);
+            resolve(0);
         });
-
-        // Keep the process running
-        process.stdin.resume();
-
-    } catch (error) {
-        spinner.fail(`Failed to create ${proxyType}`);
-        console.error(chalk.red(`Error: ${error.message}`));
-
-        // Clean up if needed
-        if (proxyId) {
-            await deleteProxy(proxyId);
-        }
-
-        process.exit(1);
-    }
+    });
 }
 
 /**
@@ -192,27 +177,22 @@ function getRandomPort(min = 50000, max = 51000) {
  * @returns {Promise<Object>} Proxy information
  */
 async function createProxy(deviceId, options) {
-    // Get configuration
-    const config = readConfig();
-
-    if (!config.token || !config.server || !config.username) {
-        throw new Error('Not configured. Run thinr without parameters to set up.');
-    }
+    const config = requireConfig();
 
     const protocol = options.web ? 'http_iotmp' : 'tcp_iotmp';
     const targetAddress = options.targetAddress || 'localhost';
     const targetPort = options.targetPort || (options.web ? 80 : 22);
     const serverPort = options.serverPort || getRandomPort();
-    const serverSecure = options.serverSecure || (!!options.web);
+    const serverSecure = options.serverSecure || !!options.web;
     const targetSecure = options.targetSecure || false;
 
     // Create a unique proxy ID based on device, protocol and a timestamp
     const timestamp = new Date().getTime().toString(36);
-    const proxyId = `${protocol}_${deviceId.slice(0,12)}_${timestamp}`;
+    const proxyId = `${protocol}_${deviceId.slice(0, 12)}_${timestamp}`;
 
     try {
         // Create proxy
-        const response = await api.post(
+        await api.post(
             `/v1/proxies`,
             {
                 enabled: true,
@@ -223,23 +203,23 @@ async function createProxy(deviceId, options) {
                         device: deviceId,
                         address: targetAddress,
                         port: targetPort,
-                        secure: targetSecure
+                        secure: targetSecure,
                     },
                     protocol: protocol,
                     source: {
                         port: serverPort,
-                        secure: serverSecure
-                    }
+                        secure: serverSecure,
+                    },
                 },
                 proxy: proxyId,
                 name: options.web ? `Web access for ${deviceId}` : `TCP proxy for ${deviceId}`,
-                description: `${options.web ? 'Web interface' : 'TCP proxy'} for ${deviceId}:${targetPort} created by ThingR CLI`
+                description: `${options.web ? 'Web interface' : 'TCP proxy'} for ${deviceId}:${targetPort} created by Thinr CLI`,
             },
             {
                 headers: {
-                    'Content-Type': 'application/json'
-                }
-            }
+                    'Content-Type': 'application/json',
+                },
+            },
         );
 
         // Determine the URL based on protocol and SSL setting
@@ -255,20 +235,10 @@ async function createProxy(deviceId, options) {
             targetPort: targetPort,
             protocol: protocol,
             serverSecure: serverSecure,
-            targetSecure: targetSecure
+            targetSecure: targetSecure,
         };
     } catch (error) {
-        if (error.response) {
-            if (error.response.status === 401) {
-                throw new Error('Unauthorized. Your token may have expired. Please reconfigure.');
-            } else {
-                throw new Error(`Server error: ${error.response.status} ${error.response.statusText}`);
-            }
-        } else if (error.request) {
-            throw new Error('No response from server. Please check your connection.');
-        } else {
-            throw new Error(`Error: ${error.message}`);
-        }
+        throw apiError(error, { notFound: `Device not found: ${deviceId}` });
     }
 }
 
@@ -285,9 +255,7 @@ async function deleteProxy(proxyId) {
     }
 
     try {
-        await api.delete(
-            `/v1/proxies/${proxyId}`,
-        );
+        await api.delete(`/v1/proxies/${proxyId}`);
 
         return true;
     } catch (error) {
@@ -302,10 +270,10 @@ async function deleteProxy(proxyId) {
  */
 async function openBrowser(url) {
     try {
-        await open(url, {app: [{name: apps.browser}, 'firefox-developer-edition']});
+        await open(url, { app: [{ name: apps.browser }, 'firefox-developer-edition'] });
         return true;
     } catch (error) {
         console.error(chalk.red(`Error opening browser: ${error.message}`));
         return false;
     }
-}
+}

package/lib/resource.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
-import { readConfig } from './config.js';
+import { requireConfig } from './config.js';
 import api from './api.js';
+import { apiError } from './errors.js';
 
 /**
  * Get device resource value
@@ -8,116 +9,149 @@ import api from './api.js';
  * @return {Promise<Object>} Resource value
  */
 export async function getDeviceResources(deviceId) {
-    // Get configuration
-    const config = readConfig();
-
-    if (!config.token || !config.server || !config.username) {
-        throw new Error('Not configured. Run thinr without parameters to set up.');
-    }
+    const config = requireConfig();
 
     try {
-        // Fetch resource value
         const response = await api.get(
             `/v3/users/${config.username}/devices/${deviceId}/resources`,
         );
-
-        // Remove hidden resources for which the keys starting with '_'
-        const filtered = Object.fromEntries(
-            Object.entries(response.data).filter(([key]) => !key.startsWith('$'))
+        // Drop internal resources whose keys start with '$'
+        return Object.fromEntries(
+            Object.entries(response.data).filter(([key]) => !key.startsWith('$')),
         );
+    } catch (error) {
+        throw apiError(error, { notFound: `Device not found: ${deviceId}` });
+    }
+}
 
-        return filtered;
+/**
+ * Read the current value of a resource via GET. Appropriate for
+ * output-only (fn=3) or fn=4 resources when you only want the latest
+ * sample, not to trigger the input side.
+ */
+export async function readDeviceResource(deviceId, resourceId) {
+    const config = requireConfig();
+    try {
+        const response = await api.get(
+            `/v3/users/${config.username}/devices/${deviceId}/resources/${resourceId}`,
+        );
+        return response.data;
     } catch (error) {
-        if (error.response) {
-            // The request was made and the server responded with a status code
-            if (error.response.status === 404) {
-                throw new Error(`Device not found: ${deviceId}`);
-            } else if (error.response.status === 401) {
-                throw new Error('Unauthorized. Your token may have expired. Please reconfigure.');
-            } else {
-                throw new Error(`Server error: ${error.response.status} ${error.response.statusText}`);
-            }
-        } else if (error.request) {
-            // The request was made but no response was received
-            throw new Error('No response from server. Please check your connection.');
-        } else {
-            // Something happened in setting up the request that triggered an Error
-            throw new Error(`Error: ${error.message}`);
-        }
+        throw apiError(error, {
+            notFound: `Resource not found: ${resourceId} on device ${deviceId}`,
+        });
     }
+}
 
+/**
+ * Introspect a single resource. Returns the `{in, out}` schema the
+ * agent advertises for that resource, e.g. for `cmd`:
+ *   { in: { cmd: "", mode: "api", timeout: 30 }, out: { stdout: "", stderr: "", retcode: 0 } }
+ *
+ * Read-only resources (fn=3) only return `out`; input-only (fn=2) only
+ * return `in`; fn=1 may return an empty object. Not every agent/firmware
+ * exposes /api — callers should tolerate 404/501.
+ */
+export async function getDeviceResourceApi(deviceId, resourceId) {
+    const config = requireConfig();
+    try {
+        const response = await api.get(
+            `/v3/users/${config.username}/devices/${deviceId}/resources/${resourceId}/api`,
+        );
+        return response.data;
+    } catch (error) {
+        throw apiError(error, {
+            notFound: `Resource not found: ${resourceId} on device ${deviceId}`,
+        });
+    }
 }
 
 /**
  * Execute a resource on a device
  */
 export async function executeDeviceResource(deviceId, resourceId, inputs) {
-    // Get configuration
-    const config = readConfig();
-
-    if (!config.token || !config.server || !config.username) {
-        throw new Error('Not configured. Run thinr without parameters to set up.');
-    }
+    const config = requireConfig();
 
     try {
-        // Execute resource
         const response = await api.post(
             `/v3/users/${config.username}/devices/${deviceId}/resources/${resourceId}`,
             inputs,
         );
-
         return response.data;
     } catch (error) {
-        if (error.response) {
-            // The request was made and the server responded with a status code
-            if (error.response.status === 404) {
-                throw new Error(`Resource not found: ${resourceId} on device ${deviceId}`);
-            } else if (error.response.status === 401) {
-                throw new Error('Unauthorized. Your token may have expired. Please reconfigure.');
-            } else {
-                throw new Error(`Server error: ${error.response.status} ${error.response.statusText}`);
-            }
-        } else if (error.request) {
-            // The request was made but no response was received
-            throw new Error('No response from server. Please check your connection.');
-        } else {
-            // Something happened in setting up the request that triggered an Error
-            throw new Error(`Error: ${error.message}`);
-        }
+        throw apiError(error, {
+            notFound: `Resource not found: ${resourceId} on device ${deviceId}`,
+        });
     }
 }
 
 /**
- * Format device resources for display
- * @param {string} deviceId - Device ID
- * @param {Object} resources - Resources data from API
- * @return {string} Formatted resources
+ * Decide GET vs POST based on whether the caller passed real inputs.
+ * No inputs (undefined, null, or an empty object) → GET, which reads
+ * the output side of fn=3/4 resources without triggering the input
+ * handler. Otherwise POST with the payload.
+ */
+export async function callDeviceResource(deviceId, resourceId, inputs) {
+    const hasInputs =
+        inputs !== undefined &&
+        inputs !== null &&
+        !(typeof inputs === 'object' && !Array.isArray(inputs) && Object.keys(inputs).length === 0);
+    return hasInputs
+        ? executeDeviceResource(deviceId, resourceId, inputs)
+        : readDeviceResource(deviceId, resourceId);
+}
+
+/**
+ * Fetch the resource list and, in parallel, introspect each resource's
+ * `/api` schema. Returns an array with `{name, fn, in?, out?}` so both
+ * the CLI and the MCP can render the same information.
  */
-export function formatDeviceResources(deviceId, resources) {
-    let formattedResources = `\nResources for device ${chalk.cyan(deviceId)}:\n`;
+export async function listDeviceResourcesWithSchemas(deviceId) {
+    const resources = await getDeviceResources(deviceId);
+    const names = Object.keys(resources);
+    const entries = await Promise.all(
+        names.map(async (name) => {
+            const fn = resources[name]?.fn;
+            try {
+                const schema = await getDeviceResourceApi(deviceId, name);
+                return { name, fn, ...schema };
+            } catch {
+                return { name, fn };
+            }
+        }),
+    );
+    return entries;
+}
 
-    //
-    if (resources && Object.keys(resources).length > 0) {
-        Object.keys(resources).forEach(key => {
-            formattedResources += `- ${chalk.green(key)}: ${chalk.blue(getResourceType(resources[key]))}\n`;
-        });
-    } else {
-        formattedResources += chalk.yellow('No resources found for this device.\n');
+/**
+ * Format the resource entries produced by listDeviceResourcesWithSchemas
+ * (`{name, fn, in?, out?}`). Shared between CLI (with chalk) and any
+ * other human-facing surface.
+ */
+export function formatDeviceResourcesWithSchemas(deviceId, entries) {
+    let out = `\nResources for device ${chalk.cyan(deviceId)}:\n`;
+    if (!entries || entries.length === 0) {
+        return out + chalk.yellow('No resources found for this device.\n');
     }
-
-    return formattedResources;
+    for (const e of entries) {
+        const kind = getResourceType({ fn: e.fn });
+        out += `\n- ${chalk.green(e.name)}  ${chalk.gray('[' + kind + ']')}\n`;
+        if (e.in !== undefined) out += `    in:  ${JSON.stringify(e.in)}\n`;
+        if (e.out !== undefined) out += `    out: ${JSON.stringify(e.out)}\n`;
+    }
+    return out;
 }
 
 function getResourceType(value) {
     switch (value.fn) {
         case 1:
-            return "no parameters";
+            return 'no parameters';
         case 2:
-            return "input";
+            return 'input';
         case 3:
-            return "output";
+            return 'output';
         case 4:
-            return "input/output";
+            return 'input/output';
         default:
             return 'unknown';
     }

package/lib/status.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
-import { readConfig } from './config.js';
+import { requireConfig } from './config.js';
 import api from './api.js';
+import { apiError } from './errors.js';
 
 /**
  * Get device status
@@ -8,38 +9,13 @@ import api from './api.js';
  * @returns {Promise<Object>} Status information
  */
 export async function getDeviceStatus(deviceId) {
-    // Get configuration
-    const config = readConfig();
-
-    if (!config.token || !config.server || !config.username) {
-        throw new Error('Not configured. Run thinr without parameters to set up.');
-    }
+    const config = requireConfig();
 
     try {
-        // Fetch device status
-        const response = await api.get(
-            `/v1/users/${config.username}/devices/${deviceId}/stats`,
-        );
-
+        const response = await api.get(`/v1/users/${config.username}/devices/${deviceId}/stats`);
         return response.data;
     } catch (error) {
-        if (error.response) {
-            // The request was made and the server responded with a status code
-            // that falls out of the range of 2xx
-            if (error.response.status === 404) {
-                throw new Error(`Device not found: ${deviceId}`);
-            } else if (error.response.status === 401) {
-                throw new Error('Unauthorized. Your token may have expired. Please reconfigure.');
-            } else {
-                throw new Error(`Server error: ${error.response.status} ${error.response.statusText}`);
-            }
-        } else if (error.request) {
-            // The request was made but no response was received
-            throw new Error('No response from server. Please check your connection.');
-        } else {
-            // Something happened in setting up the request that triggered an Error
-            throw new Error(`Error: ${error.message}`);
-        }
+        throw apiError(error, { notFound: `Device not found: ${deviceId}` });
     }
 }
 
@@ -50,9 +26,7 @@ export async function getDeviceStatus(deviceId) {
  * @returns {string} Formatted status
  */
 export function formatDeviceStatus(deviceId, status) {
-    const connectedStatus = status.connected ?
-        chalk.green('● Online') :
-        chalk.red('○ Offline');
+    const connectedStatus = status.connected ? chalk.green('● Online') : chalk.red('○ Offline');
 
     // Format connected time
     let connectedTime = '';
@@ -93,4 +67,4 @@ Data Transfer:
 `;
 
     return output;
-}
+}