cisco-axl 1.4.1 → 2.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run type-check
+
+      - name: Build
+        run: npm run build
+
+      - name: Verify ESM import
+        run: node --input-type=module -e "import axlService from './main.mjs'; console.log('ESM import OK');"
+
+      - name: Verify CJS require
+        run: node -e "const axlService = require('./dist/index.js'); console.log('CJS require OK');"

package/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write    # Required for OIDC authentication
+  contents: write    # Required for creating GitHub Release
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run type-check
+
+      - name: Build
+        run: npm run build
+
+      - name: Verify ESM import
+        run: node --input-type=module -e "import axlService from './main.mjs'; console.log('ESM import OK');"
+
+      - name: Verify CJS require
+        run: node -e "const axlService = require('./dist/index.js'); console.log('CJS require OK');"
+
+      - name: Publish to npm
+        run: npm publish --access public
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

package/README.md

@@ -1,186 +1,295 @@
-# Cisco AXL SOAP Library
+# Cisco AXL Library & CLI
 
-A Javascript library to pull AXL data Cisco CUCM via SOAP. The goal of this project is to make it easier for people to use AXL and to include all functionality of AXL. This library utilizes [strong-soap](https://www.npmjs.com/package/strong-soap) to read Cisco's WSDL file. As a result this library can use any function in the schema for the version that you specify.
+A JavaScript library and CLI to interact with Cisco CUCM via AXL SOAP API. Dynamically discovers all AXL operations from the WSDL schema — any operation for your specified version is available without static definitions.
 
 Administrative XML (AXL) information can be found at:
 [Administrative XML (AXL) Reference](https://developer.cisco.com/docs/axl/#!axl-developer-guide).
 
 ## Installation
 
-Using npm:
+```bash
+npm install cisco-axl
+```
 
-```javascript
-npm i -g npm
-npm i --save cisco-axl
+### Global CLI install
+
+```bash
+npm install -g cisco-axl
+```
+
+Or run without installing:
+
+```bash
+npx cisco-axl --help
+```
+
+### AI Agent Skills
+
+```bash
+npx skillsadd sieteunoseis/cisco-axl
 ```
 
 ## Requirements
 
-This package uses the built in Fetch API of Node. This feature was first introduced in Node v16.15.0. You may need to enable expermential vm module. Also you can disable warnings with an optional enviromental variable.
+If you are using self-signed certificates on Cisco VOS products you may need to disable TLS verification, or use the `--insecure` CLI flag.
 
-Also if you are using self signed certificates on Cisco VOS products you may need to disable TLS verification. This makes TLS, and HTTPS by extension, insecure. The use of this environment variable is strongly discouraged. Please only do this in a lab enviroment.
+Supported CUCM versions: `11.0`, `11.5`, `12.0`, `12.5`, `14.0`, `15.0`
 
-Suggested enviromental variables:
+## CLI
 
-```env
-NODE_OPTIONS=--experimental-vm-modules
-NODE_NO_WARNINGS=1
-NODE_TLS_REJECT_UNAUTHORIZED=0
-```
+The CLI provides full AXL access from the command line — CRUD operations, SQL queries, operation discovery, bulk provisioning from CSV, and a raw execute escape hatch for any AXL operation.
+
+### Quick Start
+
+```bash
+# Configure a cluster
+cisco-axl config add lab --host 10.0.0.1 --username admin --password secret --cucm-version 14.0 --insecure
+
+# Test the connection
+cisco-axl config test
 
-### Debugging
+# List phones
+cisco-axl list Phone --search "name=SEP%"
 
-You can enable debug logging by setting the `DEBUG` environment variable to any truthy value (except 'false', 'no', '0', 'off', or 'n'). When enabled, debug logs will show detailed information about authentication tests and operations being executed.
+# Get a specific phone
+cisco-axl get Phone SEP001122334455 --returned-tags "name,model,description"
 
-```env
-DEBUG=true
+# SQL query
+cisco-axl sql query "SELECT name, description FROM device WHERE name LIKE 'SEP%'"
+
+# Discover available operations
+cisco-axl operations --filter phone
+cisco-axl operations --type action --filter phone
+
+# Describe what tags an operation needs
+cisco-axl describe getPhone --detailed
+
+# Execute any AXL operation
+cisco-axl execute doLdapSync --tags '{"name":"LDAP_Main"}'
 ```
 
-Debug logs will be prefixed with `[AXL DEBUG]` and include information such as:
-- Authentication test attempts and responses
-- Operations being executed
-- API responses
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `config add/use/list/show/remove/test` | Manage multi-cluster configurations |
+| `get <type> <identifier>` | Get a single item |
+| `list <type>` | List items with search, pagination, returned tags |
+| `add <type>` | Add an item (inline JSON, template, or bulk CSV) |
+| `update <type> <identifier>` | Update an item |
+| `remove <type> <identifier>` | Remove an item |
+| `sql query/update` | Execute SQL against CUCM |
+| `execute <operation>` | Run any raw AXL operation |
+| `operations` | List available operations with `--filter` and `--type crud\|action` |
+| `describe <operation>` | Show tag schema with `--detailed` for required/optional/type info |
+
+### Configuration
+
+```bash
+# Multiple clusters
+cisco-axl config add lab --host 10.0.0.1 --username admin --password secret --cucm-version 14.0 --insecure
+cisco-axl config add prod --host 10.0.0.2 --username axladmin --password secret --cucm-version 15.0 --insecure
+cisco-axl config use prod
+cisco-axl config list
+
+# Per-command cluster override
+cisco-axl list Phone --search "name=SEP%" --cluster lab
+
+# Environment variables (CI/CD, AI agents)
+export CUCM_HOST=10.0.0.1 CUCM_USERNAME=admin CUCM_PASSWORD=secret CUCM_VERSION=14.0
+```
 
-This is especially helpful when troubleshooting authentication issues or unexpected API behavior.
+Config stored at `~/.cisco-axl/config.json`. Supports optional [Secret Server](https://github.com/sieteunoseis/ss-cli) integration via `<ss:ID:field>` placeholders.
 
-## Features
+### Output Formats
 
-- This library uses strong-soap to parse the AXL WSDL file. As a result any AXL function for your specified version is avaliable to use!
-- Supports the Promise API. Can chain procedures together or you could use Promise.all() to run multiple "get" operations at the same time.
-- Returns all results in JSON rather than XML. Function has options to remove all blank or empty fields from JSON results via optional clean parameter.
-- Support for [json-variables](https://codsen.com/os/json-variables). The executeOperation function will recognize the dataContainerIdentifierTails from json-variables and remove them from your call. This avoids any SOAP fault issues from having extra information in call. See examples folder for use case.
-- TypeScript support with type definitions for better developer experience and code reliability
-- Authentication testing with the testAuthentication method to verify credentials before executing operations
-- Debug logging capabilities to help troubleshoot API interactions by setting the DEBUG environment variable
+```bash
+cisco-axl list Phone --search "name=SEP%" --format table  # default, human-readable
+cisco-axl list Phone --search "name=SEP%" --format json   # structured JSON
+cisco-axl list Phone --search "name=SEP%" --format toon   # token-efficient for AI agents
+cisco-axl list Phone --search "name=SEP%" --format csv    # spreadsheet export
+```
 
-## Usage
+### Bulk Operations from CSV
 
-```javascript
-const axlService = require("cisco-axl");
+Requires optional packages: `npm install json-variables csv-parse`
 
-let service = new axlService("10.10.20.1", "administrator", "ciscopsdt","14.0");
-
-var operation = "addRoutePartition";
-var tags = {
-  routePartition: {
-    name: "INTERNAL-PT",
-    description: "Internal directory numbers",
-    timeScheduleIdName: "",
-    useOriginatingDeviceTimeZone: "",
-    timeZone: "",
-    partitionUsage: "",
-  },
-};
+```bash
+# Bulk add phones from template + CSV
+cisco-axl add Phone --template phone-template.json --csv phones.csv
+cisco-axl add Phone --template phone-template.json --csv phones.csv --dry-run  # preview first
+
+# Single template with inline vars
+cisco-axl add Phone --template phone-template.json --vars '{"mac":"001122334455","dp":"DP_HQ"}'
+```
+
+Template file (`phone-template.json`):
+```json
+{
+  "name": "SEP%%mac%%",
+  "devicePoolName": "%%devicePool%%",
+  "description": "%%description%%",
+  "protocol": "SIP"
+}
+```
 
-service
-  .executeOperation(operation, tags)
-  .then((results) => {
-    console.log("addRoutePartition UUID", results);
-  })
-  .catch((error) => {
-    console.log(error);
-  });
+### Global Flags
+
+```
+--format table|json|toon|csv   Output format (default: table)
+--insecure                     Skip TLS certificate verification
+--clean                        Remove empty/null values from results
+--no-attributes                Remove XML attributes from results
+--read-only                    Restrict to read-only operations
+--no-audit                     Disable audit logging for this command
+--debug                        Enable debug logging
 ```
 
-## Methods
+### Audit Trail
 
-- new axlService(options: obj)
-- axlService.testAuthentication()
-- axlService.returnOperations(filter?: string)
-- axlService.getOperationTags(operation: string)
-- axlService.executeOperation(operation: string,tags: obj, opts?: obj)
+All operations are logged to `~/.cisco-axl/audit.jsonl` (JSONL format). Credentials are never logged. Use `--no-audit` to skip.
 
-### new axlService(options)
+## Library API
 
-Service constructor for methods. Requires a JSON object consisting of hostname, username, password and version.
+### Setup
+
+```javascript
+const axlService = require("cisco-axl");
 
-```node
 let service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0");
+
+// With options
+let service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0", {
+  logging: { level: "info" },
+  retry: { retries: 3, retryDelay: 1000 }
+});
 ```
 
-### service.testAuthentication() ⇒ Returns promise
+### Logging
 
-Tests the authentication credentials against the AXL endpoint. Returns a promise that resolves to `true` if authentication is successful, or rejects with an error if authentication fails.
+```javascript
+// Via environment variable
+// DEBUG=true
+
+// Via constructor
+let service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0", {
+  logging: {
+    level: "info",  // "error" | "warn" | "info" | "debug"
+    handler: (level, message, data) => {
+      myLogger[level](message, data);
+    }
+  }
+});
 
-```node
-service.testAuthentication()
-  .then((success) => {
-    console.log('Authentication successful');
-  })
-  .catch((error) => {
-    console.error('Authentication failed:', error.message);
-  });
+// Change at runtime
+service.setLogLevel("debug");
 ```
 
-### service.returnOperations(filter?) ⇒ Returns promise
+### Convenience Methods
 
-Method takes optional argument to filter results. No argument returns all operations. Returns results via Promise.
+```javascript
+// Get a single item by name or UUID
+await service.getItem("Phone", "SEP001122334455");
+await service.getItem("Phone", { uuid: "abc-123" });
+
+// List items with search criteria and returned tags
+await service.listItems("RoutePartition");  // all partitions
+await service.listItems("Phone", { name: "SEP%" }, { name: "", model: "" });
+
+// Add, update, remove
+await service.addItem("RoutePartition", { name: "NEW-PT", description: "New" });
+await service.updateItem("Phone", "SEP001122334455", { description: "Updated" });
+await service.removeItem("RoutePartition", "NEW-PT");
+
+// SQL
+const rows = await service.executeSqlQuery("SELECT name FROM routepartition");
+await service.executeSqlUpdate("UPDATE routepartition SET description='test' WHERE name='NEW-PT'");
+```
 
-| Method           | Argument | Type   | Obligatory | Description                         |
-| :--------------- | :------- | :----- | :--------- | :---------------------------------- |
-| returnOperations | filter   | string | No         | Provide a string to filter results. |
+### Operation Discovery
 
-### service.getOperationTags(operation) ⇒ Returns promise
+```javascript
+// List all operations
+const ops = await service.returnOperations();
+const phoneOps = await service.returnOperations("phone");
 
-Method requires passing an AXL operation. Returns results via Promise.
+// Get tag schema
+const tags = await service.getOperationTags("addRoutePartition");
 
-| Method           | Argument  | Type   | Obligatory | Description                                                              |
-| :--------------- | :-------- | :----- | :--------- | :----------------------------------------------------------------------- |
-| getOperationTags | operation | string | Yes        | Provide the name of the AXL operation you wish to retrieve the tags for. |
+// Get detailed metadata (required, nillable, type)
+const detailed = await service.getOperationTagsDetailed("addRoutePartition");
+console.log(detailed.routePartition.required);  // true
+console.log(detailed.routePartition.children.name.type);  // "string"
+```
 
-### service.executeOperation(operation,tags,opts?) ⇒ Returns promise
+### Execute Any Operation
 
-Method requires passing an AXL operation and JSON object of tags. Returns results via Promise.
+```javascript
+const tags = await service.getOperationTags("addRoutePartition");
+tags.routePartition.name = "INTERNAL-PT";
+tags.routePartition.description = "Internal directory numbers";
 
-Current options include:
-| option | type | description |
-| :--------------------------- | :------ | :---------------------------------------------------------------------------------- |
-| clean | boolean | Default: **false**. Allows method to remove all tags that have no values from return data. |
-| removeAttributes | boolean | Default: **false**. Allows method to remove all attributes tags return data. |
-| dataContainerIdentifierTails | string | Default: **'\_data'**. executeOperation will automatically remove any tag with the defined string. This is used with json-variables library. |
+const result = await service.executeOperation("addRoutePartition", tags);
+console.log("UUID:", result);
+```
 
-Example:
+### Batch Operations
 
-```node
-var opts = {
-  clean: true,
-  removeAttributes: false,
-  dataContainerIdentifierTails: "_data",
-};
+```javascript
+const results = await service.executeBatch([
+  { operation: "getPhone", tags: { name: "SEP001122334455" } },
+  { operation: "getPhone", tags: { name: "SEP556677889900" } },
+], 5); // concurrency limit
+
+results.forEach((r) => {
+  console.log(r.success ? `${r.operation}: OK` : `${r.operation}: ${r.error.message}`);
+});
 ```
 
-| Method           | Argument  | Type   | Obligatory | Description                                                |
-| :--------------- | :-------- | :----- | :--------- | :--------------------------------------------------------- |
-| executeOperation | operation | string | Yes        | Provide the name of the AXL operation you wish to execute. |
-| executeOperation | tags      | object | Yes        | Provide a JSON object of the tags for your operation.      |
-| executeOperation | opts      | object | No         | Provide a JSON object of options for your operation.       |
-
-## Examples
+### Error Handling
 
-Check **examples** folder for different ways to use this library. Each folder should have a **README** to explain about each example.
+```javascript
+const { AXLAuthError, AXLNotFoundError, AXLOperationError, AXLValidationError } = require("cisco-axl");
+
+try {
+  await service.executeOperation("getPhone", { name: "INVALID" });
+} catch (error) {
+  if (error instanceof AXLAuthError) console.log("Bad credentials");
+  else if (error instanceof AXLNotFoundError) console.log("Operation not found:", error.operation);
+  else if (error instanceof AXLOperationError) console.log("SOAP fault:", error.message);
+  else if (error instanceof AXLValidationError) console.log("Invalid input:", error.message);
+}
+```
 
-You can also run the **tests.js** against Cisco's DevNet sandbox so see how each various method works.
+### Retry Configuration
 
 ```javascript
-npm run test
+let service = new axlService("10.10.20.1", "admin", "pass", "14.0", {
+  retry: {
+    retries: 3,
+    retryDelay: 1000,
+    retryOn: (error) => error.message.includes("ECONNRESET")
+  }
+});
 ```
 
-Note: Test are using Cisco's DevNet sandbox information. Find more information here: [Cisco DevNet](https://devnetsandbox.cisco.com/).
-
-## json-variables support
+### ESM Support
 
-At a tactical level, json-variables program lets you take a plain object (JSON files contents) and add special markers in any value which you can then reference in a different path.
+```javascript
+// CommonJS
+const axlService = require("cisco-axl");
 
-This library will recoginize json-variables **\*\_data** keys in the tags and delete before executing the operation.
+// ESM
+import axlService from "cisco-axl";
+import { AXLAuthError, AXLOperationError } from "cisco-axl";
+```
 
-Example:
+### json-variables Support
 
-```node
+```javascript
 var lineTemplate = {
   pattern: "%%_extension_%%",
-  routePartitionName: "",
   alertingName: "%%_firstName_%% %%_lastName_%%",
-  asciiAlertingName: "%%_firstName_%% %%_lastName_%%",
   description: "%%_firstName_%% %%_lastName_%%",
   _data: {
     extension: "1001",
@@ -190,71 +299,59 @@ var lineTemplate = {
 };
 
 const lineTags = jVar(lineTemplate);
-
-service
-  .executeOperation("updateLine", lineTags)
-  .then((results) => {
-    console.log(results);
-  })
-  .catch((error) => {
-    console.log(error);
-  });
+await service.executeOperation("updateLine", lineTags);
 ```
 
-Note: If you need to change the variables key you can so via options in both the json-variables and with executeOperations.
-
-Example:
+## Methods Reference
+
+### Core
+
+| Method | Description |
+|--------|-------------|
+| `new axlService(host, user, pass, version, opts?)` | Constructor |
+| `testAuthentication()` | Test credentials against AXL endpoint |
+| `returnOperations(filter?)` | List available operations |
+| `getOperationTags(operation)` | Get tag schema for an operation |
+| `getOperationTagsDetailed(operation)` | Get detailed tag metadata (required/nillable/type) |
+| `executeOperation(operation, tags, opts?)` | Execute any AXL operation |
+| `executeBatch(operations[], concurrency?)` | Parallel batch execution |
+| `setLogLevel(level)` | Change log level at runtime |
+
+### Convenience
+
+| Method | Description |
+|--------|-------------|
+| `getItem(type, identifier, opts?)` | Get single item by name or UUID |
+| `listItems(type, search?, returnedTags?, opts?)` | List items with filtering |
+| `addItem(type, data, opts?)` | Add a new item |
+| `updateItem(type, identifier, updates, opts?)` | Update an existing item |
+| `removeItem(type, identifier, opts?)` | Remove an item |
+| `executeSqlQuery(sql)` | Run a SQL SELECT query |
+| `executeSqlUpdate(sql)` | Run a SQL INSERT/UPDATE/DELETE |
 
-```node
-...
-const lineTags = jVar(lineTemplate,{ dataContainerIdentifierTails: "_variables"});
+## Examples
 
-service.executeOperation("updateLine", lineTags,{ dataContainerIdentifierTails: "_variables"})
-...
-```
+Check the **examples** folder for different ways to use this library.
 
-## Limitations
+Run the integration tests against a CUCM cluster:
 
-Currently there is an issue with strong-soap regarding returning nillable values for element tags. These values show if a particular tags is optional or not. Once resolved a method will be added to return tags nillable status (true or false).
+```bash
+npm run staging
+```
 
 ## TypeScript Support
 
-This library includes TypeScript declarations to provide type safety and improved developer experience.
-
-### TypeScript Usage
-
 ```typescript
 import axlService from 'cisco-axl';
 
-const service = new axlService(
-  "10.10.20.1",
-  "administrator",
-  "ciscopsdt",
-  "14.0"
-);
-
-async function getPartitions() {
-  try {
-    const operation = "listRoutePartition";
-    const tags = await service.getOperationTags(operation);
-    tags.searchCriteria.name = "%%";
-    
-    const result = await service.executeOperation(operation, tags);
-    return result.routePartition;
-  } catch (error) {
-    console.error("Error fetching partitions:", error);
-    throw error;
-  }
-}
-```
-
-See the `examples/typescript` directory for more TypeScript examples.
+const service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0");
 
-## TODO
+const tags = await service.getOperationTags("listRoutePartition");
+tags.searchCriteria.name = "%%";
+const result = await service.executeOperation("listRoutePartition", tags);
+```
 
-- Add more promised based examples, particularly a Promise.All() example.
-- Add example for reading in CSV and performing a bulk exercise with variables.
-- Add example for saving SQL output to CSV.
+See the `examples/typescript` directory for more examples.
 
 ## Giving Back
 

package/bin/cisco-axl.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../cli/index.js");