{"_id":"@burna-org/awx-client","_rev":"2-e3c25d20e88621261fb7281b38f68904","name":"@burna-org/awx-client","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@burna-org/awx-client","version":"0.0.1","keywords":["awx","ansible","client","nodejs"],"author":{"name":"Burna Team"},"license":"MIT","_id":"@burna-org/awx-client@0.0.1","maintainers":[{"name":"radiumgh","email":"mail.rezaghanbari@gmail.com"}],"dist":{"shasum":"fffcefd86437ded92edcc26dc87daf449cffb689","tarball":"https://registry.npmjs.org/@burna-org/awx-client/-/awx-client-0.0.1.tgz","fileCount":44,"integrity":"sha512-WjZ5ePE2+86Y35ownqBr2YnKHSDHd+4lGyqkn9HF+1Vg2WlFDiGhuOmzgzGP2HsfqQV72d6b51whJizOtW7aug==","signatures":[{"sig":"MEUCIQC1bEav5Xu8MPMmDHc9Gmsy6/8cRvOoR7LGY2SUDkP1TAIgUc/ZcuQ3vcZpYYOcsiSUlOQUehgnR2UCsRxaUgEJyKY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":171633},"main":"index.js","types":"dist/types/index.d.ts","scripts":{"test":"jest --runInBand","prepack":"npm run clean:types && npm run build:types","typecheck":"tsc -p tsconfig.json --noEmit","build:types":"tsc -p tsconfig.types.json","clean:types":"rm -rf dist/types","test:coverage":"jest --runInBand --coverage"},"_npmUser":{"name":"radiumgh","email":"mail.rezaghanbari@gmail.com"},"_npmVersion":"11.6.2","description":"AWX client library extracted from OS.js service providers","directories":{},"_nodeVersion":"24.11.1","dependencies":{"axios":"^1.13.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","typescript":"^5.6.3"},"_npmOperationalInternal":{"tmp":"tmp/awx-client_0.0.1_1771488288487_0.8217299750846099","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@burna-org/awx-client","version":"0.0.2","description":"AWX client library extracted from OS.js service providers","main":"index.js","types":"dist/types/index.d.ts","scripts":{"test":"jest --runInBand","test:coverage":"jest --runInBand --coverage","typecheck":"tsc -p tsconfig.json --noEmit","build:types":"tsc -p tsconfig.types.json","clean:types":"rm -rf dist/types","prepack":"npm run clean:types && npm run build:types"},"keywords":["awx","ansible","client","nodejs"],"author":{"name":"Burna Team"},"license":"MIT","dependencies":{"axios":"^1.13.2"},"publishConfig":{"access":"public"},"devDependencies":{"jest":"^29.7.0","typescript":"^5.6.3"},"gitHead":"1eb6ac178084dd69d3deda191922332ea1b6b66a","_id":"@burna-org/awx-client@0.0.2","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-m8YyN1c5mRlZV6TBpkdVSMAQ9+dcF1aBD/k9zDwhfN7qmsEd+OsOw0ajIG2WygEYdcFL5krTF/zh8mOX395ZMQ==","shasum":"df716ed3945757eda2f36552d1d4753c36015280","tarball":"https://registry.npmjs.org/@burna-org/awx-client/-/awx-client-0.0.2.tgz","fileCount":47,"unpackedSize":182147,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBlnyEol8m6CFtvH26EqbsPdh1K0CkyZ0IkTDgwxuBeuAiAYsoyfDfBahFuekRlIeNOmOZ2Bn9dLTlpLGA5a1wliEA=="}]},"_npmUser":{"name":"radiumgh","email":"mail.rezaghanbari@gmail.com"},"directories":{},"maintainers":[{"name":"radiumgh","email":"mail.rezaghanbari@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/awx-client_0.0.2_1771582507274_0.6448522703456103"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-19T08:04:48.397Z","modified":"2026-02-20T10:15:07.595Z","0.0.1":"2026-02-19T08:04:48.619Z","0.0.2":"2026-02-20T10:15:07.450Z"},"author":{"name":"Burna Team"},"license":"MIT","keywords":["awx","ansible","client","nodejs"],"description":"AWX client library extracted from OS.js service providers","maintainers":[{"name":"radiumgh","email":"mail.rezaghanbari@gmail.com"}],"readme":"# @burna-org/awx-client\n\nAWX API client for Node.js. This package wraps AWX REST endpoints and handles token lifecycle automatically.\n\n## Install\n\n```bash\nnpm install @burna-org/awx-client\n```\n\n## What you get\n\n- Automatic token fetch/refresh before each API call\n- Simple CommonJS client (`AWXClient`)\n- Direct access to low-level connector (`AwxRestConnector`) if you need custom AWX endpoints\n\n## Quick start (server)\n\n```js\nconst AWXClient = require('@burna-org/awx-client');\n\nconst awx = new AWXClient({\n  host: process.env.AWX_HOST,\n  username: process.env.AWX_USERNAME,\n  password: process.env.AWX_PASSWORD,\n});\n\nasync function healthCheck() {\n  const organizations = await awx.listOrganizations({options: {page_size: 5}});\n  return organizations.count;\n}\n```\n\n## Configuration\n\nCreate the client with:\n\n- `host` (required): AWX base URL, for example `http://awx.example.com`\n- `username` (required): AWX username\n- `password` (required): AWX password\n- `runtimeMock` (optional, default `false`): when `true`, returns built-in mock AWX responses and avoids real HTTP requests.\n\nIf any required values are missing while `runtimeMock` is `false`, constructor throws `AWX_01`.\n\n## Auth behavior\n\nEvery public client method calls `before()` internally:\n\n1. Resolve API resources from AWX (`/api/`, then current version)\n2. Request/access a bearer token (`/tokens/`)\n3. Refresh token when expired\n4. Execute requested API operation\n\nIf API discovery/token setup fails in connector internals, errors may surface as `AWX_02`.\n\n## API reference\n\nAll methods return a Promise with AWX response data.\n\n### Auth\n\n- `getAccessToken({ options })`\n  - `options` examples: `description`, `application`, `scope`\n\n### Inventory\n\n- `listInventories({ options })`\n- `listInventoryHosts({ id, options })` (`id` required)\n- `createInventory({ name, organization, options })` (`name`, `organization` required)\n- `manageInventoryHost({ id, options })` (`id` required)\n\n### Jobs\n\n- `listJobs({ options })`\n- `retrieveJob({ id })` (`id` required)\n- `retrieveJobStdout({ id, options })` (`id` required)\n  - `options.format`: `api | html | txt | ansi | json | txt_download | ansi_download`\n- `listJobEvents({ id, options })` (`id` required)\n\n### Job templates\n\n- `listJobTemplates({ options })`\n- `createJobTemplate({ name, project, inventory, playbook, options })`\n  - Required: `name`, `project`, `inventory`, `playbook`\n  - `options.extra_vars` accepts object or string\n- `updateJobTemplate({ id, options })` (`id` required)\n- `launchJobTemplate({ id, options })` (`id` required)\n- `listJobsForTemplate({ id, options })` (`id` required)\n- `manageJobTemplateCredential({ id, options })` (`id` required)\n  - `options.inputs` accepts object or string\n\n### Ad hoc commands\n\n- `listAdhocCommands({ options })`\n- `retrieveAdhocCommand({ id })` (`id` required)\n- `retrieveAdhocCommandStdout({ id, options })` (`id` required)\n- `createAdhocCommand({ module_name, inventory, credential, options })`\n  - Required: `module_name`, `inventory`, `credential`\n\n### Projects\n\n- `listProjects({ options })`\n- `createProject({ name, organization, options })` (`name`, `organization` required)\n\n### Credentials\n\n- `listCredentials({ options })`\n- `createCredential({ name, credential_type, options })` (`name`, `credential_type` required)\n\n### Organizations\n\n- `listOrganizations({ options })`\n- `createOrganization({ name, options })` (`name` required)\n\n### Hosts\n\n- `updateHost({ id, options })` (`id` required)\n- `listHosts({ options })`\n- `listHostGroups({ id, options })` (`id` required)\n\n### Groups\n\n- `createGroup({ name, inventory, options })` (`name`, `inventory` required)\n- `updateGroup({ id, options })` (`id` required)\n- `listGroups({ options })`\n- `listGroupHosts({ id, options })` (`id` required)\n- `manageGroupHost({ id, options })` (`id` required; pass `options: {}` if empty)\n\n### Execution environments\n\n- `listExecutionEnvironments({ options })`\n\n### Settings\n\n- `listSettingCategories({})`\n- `listSettings({ category })` (default: `all`)\n- `updateSettings({ category, data })`\n  - `data` required and must be non-empty object\n\n## Common `options` pattern\n\nMost list APIs accept `options` and convert them into query parameters with `URLSearchParams`.\n\nTypical keys:\n\n- `search`\n- `page`\n- `page_size`\n- AWX filters like `name`, `inventory__name`, `order_by`, etc.\n\n## Practical examples\n\n### 1) List inventory hosts\n\n```js\nconst hosts = await awx.listInventoryHosts({\n  id: 12,\n  options: {page: 1, page_size: 50},\n});\n```\n\n### 2) Create and launch a job template\n\n```js\nconst template = await awx.createJobTemplate({\n  name: 'Deploy App',\n  project: 10,\n  inventory: 20,\n  playbook: 'deploy.yml',\n  options: {\n    execution_environment: 2,\n    extra_vars: {release: '2026.02'},\n    ask_variables_on_launch: true,\n  },\n});\n\nconst launch = await awx.launchJobTemplate({\n  id: template.id,\n  options: {\n    limit: 'web-01',\n    extra_vars: {canary: true},\n  },\n});\n\nconst job = await awx.retrieveJob({id: launch.id});\n```\n\n### 3) Read job events and stdout\n\n```js\nconst events = await awx.listJobEvents({\n  id: 442,\n  options: {page: 1, page_size: 200},\n});\n\nconst stdout = await awx.retrieveJobStdout({\n  id: 442,\n  options: {format: 'txt'},\n});\n```\n\n### 4) Update settings category\n\n```js\nawait awx.updateSettings({\n  category: 'jobs',\n  data: {\n    DEFAULT_JOB_TIMEOUT: 7200,\n  },\n});\n```\n\n## Low-level connector (optional)\n\nIf you need raw dynamic endpoint calls:\n\n```js\nconst {AwxRestConnector} = require('@burna-org/awx-client');\n\nconst connector = new AwxRestConnector(\n  process.env.AWX_HOST,\n  process.env.AWX_USERNAME,\n  process.env.AWX_PASSWORD\n);\n\nconst me = await connector.callDynamic('GET', '/api/v2/me/');\n```\n\n## Error handling pattern\n\n```js\ntry {\n  const data = await awx.listProjects({options: {page_size: 20}});\n  console.log(data.results);\n} catch (error) {\n  // axios errors, AWX validation errors, or connector errors (AWX_01 / AWX_02)\n  console.error(error.message);\n}\n```\n\n## Development\n\n```bash\nnpm test\nnpm run typecheck\nnpm run build:types\n```\n","readmeFilename":"README.md"}