@burna-org/awx-client

AWX API client for Node.js. This package wraps AWX REST endpoints and handles token lifecycle automatically.

Install

npm install @burna-org/awx-client

What you get

• Automatic token fetch/refresh before each API call
• Simple CommonJS client (AWXClient)
• Direct access to low-level connector (AwxRestConnector) if you need custom AWX endpoints

Quick start (server)

const AWXClient = require('@burna-org/awx-client');

const awx = new AWXClient({
  host: process.env.AWX_HOST,
  username: process.env.AWX_USERNAME,
  password: process.env.AWX_PASSWORD,
});

async function healthCheck() {
  const organizations = await awx.listOrganizations({options: {page_size: 5}});
  return organizations.count;
}

Configuration

Create the client with:

• host (required): AWX base URL, for example http://awx.example.com
• username (required): AWX username
• password (required): AWX password
• runtimeMock (optional, default false): when true, returns built-in mock AWX responses and avoids real HTTP requests.

If any required values are missing while runtimeMock is false, constructor throws AWX_01.

Auth behavior

Every public client method calls before() internally:

1. Resolve API resources from AWX (/api/, then current version)
2. Request/access a bearer token (/tokens/)
3. Refresh token when expired
4. Execute requested API operation

If API discovery/token setup fails in connector internals, errors may surface as AWX_02.

API reference

All methods return a Promise with AWX response data.

Auth

• getAccessToken({ options })
  • options examples: description, application, scope

Inventory

• listInventories({ options })
• listInventoryHosts({ id, options }) (id required)
• createInventory({ name, organization, options }) (name, organization required)
• manageInventoryHost({ id, options }) (id required)

Jobs

• listJobs({ options })
• retrieveJob({ id }) (id required)
• retrieveJobStdout({ id, options }) (id required)
  • options.format: api | html | txt | ansi | json | txt_download | ansi_download
• listJobEvents({ id, options }) (id required)

Job templates

• listJobTemplates({ options })
• createJobTemplate({ name, project, inventory, playbook, options })
  • Required: name, project, inventory, playbook
  • options.extra_vars accepts object or string
• updateJobTemplate({ id, options }) (id required)
• launchJobTemplate({ id, options }) (id required)
• listJobsForTemplate({ id, options }) (id required)
• manageJobTemplateCredential({ id, options }) (id required)
  • options.inputs accepts object or string

Ad hoc commands

• listAdhocCommands({ options })
• retrieveAdhocCommand({ id }) (id required)
• retrieveAdhocCommandStdout({ id, options }) (id required)
• createAdhocCommand({ module_name, inventory, credential, options })
  • Required: module_name, inventory, credential

Projects

• listProjects({ options })
• createProject({ name, organization, options }) (name, organization required)

Credentials

• listCredentials({ options })
• createCredential({ name, credential_type, options }) (name, credential_type required)

Organizations

• listOrganizations({ options })
• createOrganization({ name, options }) (name required)

Hosts

• updateHost({ id, options }) (id required)
• listHosts({ options })
• listHostGroups({ id, options }) (id required)

Groups

• createGroup({ name, inventory, options }) (name, inventory required)
• updateGroup({ id, options }) (id required)
• listGroups({ options })
• listGroupHosts({ id, options }) (id required)
• manageGroupHost({ id, options }) (id required; pass options: {} if empty)

Execution environments

• listExecutionEnvironments({ options })

Settings

• listSettingCategories({})
• listSettings({ category }) (default: all)
• updateSettings({ category, data })
  • data required and must be non-empty object

Common options pattern

Most list APIs accept options and convert them into query parameters with URLSearchParams.

Typical keys:

• search
• page
• page_size
• AWX filters like name, inventory__name, order_by, etc.

Practical examples

1) List inventory hosts

const hosts = await awx.listInventoryHosts({
  id: 12,
  options: {page: 1, page_size: 50},
});

2) Create and launch a job template

const template = await awx.createJobTemplate({
  name: 'Deploy App',
  project: 10,
  inventory: 20,
  playbook: 'deploy.yml',
  options: {
    execution_environment: 2,
    extra_vars: {release: '2026.02'},
    ask_variables_on_launch: true,
  },
});

const launch = await awx.launchJobTemplate({
  id: template.id,
  options: {
    limit: 'web-01',
    extra_vars: {canary: true},
  },
});

const job = await awx.retrieveJob({id: launch.id});

3) Read job events and stdout

const events = await awx.listJobEvents({
  id: 442,
  options: {page: 1, page_size: 200},
});

const stdout = await awx.retrieveJobStdout({
  id: 442,
  options: {format: 'txt'},
});

4) Update settings category

await awx.updateSettings({
  category: 'jobs',
  data: {
    DEFAULT_JOB_TIMEOUT: 7200,
  },
});

Low-level connector (optional)

If you need raw dynamic endpoint calls:

const {AwxRestConnector} = require('@burna-org/awx-client');

const connector = new AwxRestConnector(
  process.env.AWX_HOST,
  process.env.AWX_USERNAME,
  process.env.AWX_PASSWORD
);

const me = await connector.callDynamic('GET', '/api/v2/me/');

Error handling pattern

try {
  const data = await awx.listProjects({options: {page_size: 20}});
  console.log(data.results);
} catch (error) {
  // axios errors, AWX validation errors, or connector errors (AWX_01 / AWX_02)
  console.error(error.message);
}

Development

npm test
npm run typecheck
npm run build:types