{"_id":"@ballastra/aero","_rev":"7-79fb906827858e999af76622c76a16a7","name":"@ballastra/aero","dist-tags":{"latest":"0.10.0"},"versions":{"0.1.0":{"name":"@ballastra/aero","version":"0.1.0","keywords":["ballastra","aero","bot","automation","sdk"],"license":"MIT","_id":"@ballastra/aero@0.1.0","maintainers":[{"name":"muditdixit","email":"muditdixit9352@gmail.com"}],"homepage":"https://github.com/jngjneir/ballastra-backend1#readme","bugs":{"url":"https://github.com/jngjneir/ballastra-backend1/issues"},"dist":{"shasum":"2fdb8d6a20268c8c97972bf5e22162537598da96","tarball":"https://registry.npmjs.org/@ballastra/aero/-/aero-0.1.0.tgz","fileCount":5,"integrity":"sha512-uZzKY7iR7DgFjDAzOF4XNaxWrCLuHZn6+98BiiyCNaZ4LQ1jvlnGifKE8FBuGhj1fLPLIECNTN4wqB0LsvP7bQ==","signatures":[{"sig":"MEUCIDGWs421iiySTJdI+G0OmYew+DzC385DzRfKke8qn0d3AiEAq6dIllUSV3BmqoganT41NSINZairp5oORy4Ub9EhARU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20861},"main":"src/index.js","type":"module","types":"src/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"gitHead":"5013a30813803dc78a5112a1977d512a03b097ae","scripts":{"test":"node --test","prepublishOnly":"node --test"},"_npmUser":{"name":"muditdixit","email":"muditdixit9352@gmail.com"},"repository":{"url":"git+https://github.com/jngjneir/ballastra-backend1.git","type":"git","directory":"packages/aero-sdk"},"_npmVersion":"11.13.0","description":"Official SDK for building Ballastra Aeros: connect, handle events and commands, and act, without writing raw Socket.IO or REST.","directories":{},"_nodeVersion":"24.15.0","dependencies":{"socket.io-client":"^4.8.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/aero_0.1.0_1788454367178_0.27451488116207523","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@ballastra/aero","version":"0.2.0","keywords":["ballastra","aero","bot","automation","sdk"],"license":"MIT","_id":"@ballastra/aero@0.2.0","maintainers":[{"name":"muditdixit","email":"muditdixit9352@gmail.com"}],"homepage":"https://github.com/jngjneir/ballastra-backend1#readme","bugs":{"url":"https://github.com/jngjneir/ballastra-backend1/issues"},"dist":{"shasum":"557712ff9809fab1a8fd4b55cce9628c934d689e","tarball":"https://registry.npmjs.org/@ballastra/aero/-/aero-0.2.0.tgz","fileCount":5,"integrity":"sha512-PJ8NNld95Bzf+8FW3vl2ipfeOskfXQz5LQjY6L60Hu8No27T9aq8YEX8lb/LV6FEv8mf3jLsWMcBMYjKl4kQUg==","signatures":[{"sig":"MEUCIGGZQzRfCjpL9w2YRjaiim9lgM/xXBo8joel4iSjEd/BAiEAiauWuI92vCzHGIkk/w/WrdgsLg3eJyvUjiBsm7EPSu0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22549},"main":"src/index.js","type":"module","types":"src/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"gitHead":"23acb8b14e16254b13d2c428d7d423289db937ba","scripts":{"test":"node --test","prepublishOnly":"node --test"},"_npmUser":{"name":"muditdixit","email":"muditdixit9352@gmail.com"},"repository":{"url":"git+https://github.com/jngjneir/ballastra-backend1.git","type":"git","directory":"packages/aero-sdk"},"_npmVersion":"11.13.0","description":"Official SDK for building Ballastra Aeros: connect, handle events and commands, and act, without writing raw Socket.IO or REST.","directories":{},"_nodeVersion":"24.15.0","dependencies":{"socket.io-client":"^4.8.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/aero_0.2.0_1788461726433_0.5492819275093035","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@ballastra/aero","version":"0.3.0","keywords":["ballastra","aero","bot","automation","sdk"],"license":"MIT","_id":"@ballastra/aero@0.3.0","maintainers":[{"name":"muditdixit","email":"muditdixit9352@gmail.com"}],"homepage":"https://github.com/jngjneir/ballastra-backend1#readme","bugs":{"url":"https://github.com/jngjneir/ballastra-backend1/issues"},"dist":{"shasum":"c505fff284d2a8589a302bcd0a41d9ab477610da","tarball":"https://registry.npmjs.org/@ballastra/aero/-/aero-0.3.0.tgz","fileCount":5,"integrity":"sha512-SI4WRCP4qyznYy+Ib7ZLNwF6o/i6IsWGMqWxuxxDM61+FGFR92+0CH+RstfWbsVTnCGC+YhNPrOxU94W9n9xaQ==","signatures":[{"sig":"MEQCIH/DqdTQjCu20ooZD+A+4UQIVwIVK/F6K/O1AIORF1tyAiAkGcZjXhamRfEDLxiMhqHgZlbhLkqMgC0V3ewF9abfpQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24864},"main":"src/index.js","type":"module","types":"src/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"gitHead":"fe92fad2a1813ce11824383dda1dc3e7a05cfea7","scripts":{"test":"node --test","prepublishOnly":"node --test"},"_npmUser":{"name":"muditdixit","email":"muditdixit9352@gmail.com"},"repository":{"url":"git+https://github.com/jngjneir/ballastra-backend1.git","type":"git","directory":"packages/aero-sdk"},"_npmVersion":"11.13.0","description":"Official SDK for building Ballastra Aeros: connect, handle events and commands, and act, without writing raw Socket.IO or REST.","directories":{},"_nodeVersion":"24.15.0","dependencies":{"socket.io-client":"^4.8.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/aero_0.3.0_1788462866280_0.9849057756264452","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@ballastra/aero","version":"0.4.0","keywords":["ballastra","aero","bot","automation","sdk"],"license":"MIT","_id":"@ballastra/aero@0.4.0","maintainers":[{"name":"muditdixit","email":"muditdixit9352@gmail.com"}],"homepage":"https://github.com/jngjneir/ballastra-backend1#readme","bugs":{"url":"https://github.com/jngjneir/ballastra-backend1/issues"},"dist":{"shasum":"92fc61b5cefa1e6d85224df6bfee0df8f016211a","tarball":"https://registry.npmjs.org/@ballastra/aero/-/aero-0.4.0.tgz","fileCount":5,"integrity":"sha512-QEMdK36bL98PHgH/bL1t1EpQdhuBhadDDtnFJ3t1QtNkfGIA5O+D0w28mOLb3C5Au7TdhdELwTKxQVS/JZGEOg==","signatures":[{"sig":"MEUCIEbtqz57xN5aeiVaPU5h5Yo78oAJidOClNYe+fSgwSM3AiEAsFhcd5jiWRZSiq5GtAgC5+xjeIiGMFgmo7q1S3xYxoc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":25363},"main":"src/index.js","type":"module","types":"src/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"gitHead":"451c99f6ca75a7a492c5c86dc539e32cb1c04691","scripts":{"test":"node --test","prepublishOnly":"node --test"},"_npmUser":{"name":"muditdixit","email":"muditdixit9352@gmail.com"},"repository":{"url":"git+https://github.com/jngjneir/ballastra-backend1.git","type":"git","directory":"packages/aero-sdk"},"_npmVersion":"11.13.0","description":"Official SDK for building Ballastra Aeros: connect, handle events and commands, and act, without writing raw Socket.IO or REST.","directories":{},"_nodeVersion":"24.15.0","dependencies":{"socket.io-client":"^4.8.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/aero_0.4.0_1788463135880_0.5068606041627113","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@ballastra/aero","version":"0.5.0","keywords":["ballastra","aero","bot","automation","sdk"],"license":"MIT","_id":"@ballastra/aero@0.5.0","maintainers":[{"name":"muditdixit","email":"muditdixit9352@gmail.com"}],"homepage":"https://github.com/jngjneir/ballastra-backend1#readme","bugs":{"url":"https://github.com/jngjneir/ballastra-backend1/issues"},"dist":{"shasum":"16b27d05d0efa79c7fe0d299244f0486f074d870","tarball":"https://registry.npmjs.org/@ballastra/aero/-/aero-0.5.0.tgz","fileCount":5,"integrity":"sha512-mAnxQU1QurEzgYT3dNonOdJ3jFyeMOSIvnmGY9X3w2v/VB9cg8+rNhhrw+gosRS07F0lnmNBFPSt5bUBafYrjA==","signatures":[{"sig":"MEYCIQC5OlUnufodTHjPPpxBNDm+bR5mTT+ikwlTHiOy0FypCQIhAKnWLK0xwMB5C7Id2HQtqy3bVrwKF87x3liZvw6I7Rxb","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27531},"main":"src/index.js","type":"module","types":"src/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"gitHead":"083c5878a3a0cf2b042ebeecd294d01941abc830","scripts":{"test":"node --test","prepublishOnly":"node --test"},"_npmUser":{"name":"muditdixit","email":"muditdixit9352@gmail.com"},"repository":{"url":"git+https://github.com/jngjneir/ballastra-backend1.git","type":"git","directory":"packages/aero-sdk"},"_npmVersion":"11.13.0","description":"Official SDK for building Ballastra Aeros: connect, handle events and commands, and act, without writing raw Socket.IO or REST.","directories":{},"_nodeVersion":"24.15.0","dependencies":{"socket.io-client":"^4.8.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/aero_0.5.0_1788463505952_0.5969886359532552","host":"s3://npm-registry-packages-npm-production"}},"0.9.0":{"name":"@ballastra/aero","version":"0.9.0","keywords":["ballastra","aero","bot","automation","sdk"],"license":"MIT","_id":"@ballastra/aero@0.9.0","maintainers":[{"name":"muditdixit","email":"muditdixit9352@gmail.com"}],"homepage":"https://github.com/jngjneir/ballastra-backend1#readme","bugs":{"url":"https://github.com/jngjneir/ballastra-backend1/issues"},"dist":{"shasum":"cea81e2bd4fa67582f794e2ee164e467e8f9fde8","tarball":"https://registry.npmjs.org/@ballastra/aero/-/aero-0.9.0.tgz","fileCount":5,"integrity":"sha512-IMB0QnMdFsWUMj8Ihw7BNYIHLG+mQudK4gptzQY+OkubgsuTbfxkhS/tRG+zapnelCytNWYsoxTO9Ue5hbUqtA==","signatures":[{"sig":"MEUCIGdQbVClHcAeYCykOr6+8lVOX/lVJ3AOZP5E5igDtwtoAiEAodRim0PGlpBJQzyzECk5ubkGxvIeJumlwv+g/HWUNOs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32237},"main":"src/index.js","type":"module","types":"src/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"gitHead":"fa37f5ab7527f41c7e0b8e2f6868991aef974f17","scripts":{"test":"node --test","prepublishOnly":"node --test"},"_npmUser":{"name":"muditdixit","email":"muditdixit9352@gmail.com"},"repository":{"url":"git+https://github.com/jngjneir/ballastra-backend1.git","type":"git","directory":"packages/aero-sdk"},"_npmVersion":"11.13.0","description":"Official SDK for building Ballastra Aeros: connect, handle events and commands, and act, without writing raw Socket.IO or REST.","directories":{},"_nodeVersion":"24.15.0","dependencies":{"socket.io-client":"^4.8.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/aero_0.9.0_1788506880538_0.526590696523449","host":"s3://npm-registry-packages-npm-production"}},"0.10.0":{"name":"@ballastra/aero","version":"0.10.0","description":"Official SDK for building Ballastra Aeros: connect, handle events and commands, and act, without writing raw Socket.IO or REST.","type":"module","main":"src/index.js","types":"src/index.d.ts","exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js"}},"scripts":{"test":"node --test","prepublishOnly":"node --test"},"keywords":["ballastra","aero","bot","automation","sdk"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/jngjneir/ballastra-backend1.git","directory":"packages/aero-sdk"},"publishConfig":{"access":"public"},"dependencies":{"socket.io-client":"^4.8.3"},"engines":{"node":">=18"},"gitHead":"a342364d618779785de0f1a19ac5cad88305d2bb","_id":"@ballastra/aero@0.10.0","bugs":{"url":"https://github.com/jngjneir/ballastra-backend1/issues"},"homepage":"https://github.com/jngjneir/ballastra-backend1#readme","_nodeVersion":"24.15.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-/ORkS1eJNMUd0hNVIjBfN1vCnmOGsTcr5FvSZzJcXlKrI/+fPagkg4GNj0oc0wkZkMNigu8lwEnDk8wut9IqNA==","shasum":"ddeb23d67099486eed8b00d20906b31ff384f619","tarball":"https://registry.npmjs.org/@ballastra/aero/-/aero-0.10.0.tgz","fileCount":5,"unpackedSize":37965,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICe5C1GNSL9BYm7p2eSCQPseCjeIu/f18yQg/OcGFBaeAiBfiwrkqqmz6Auvy4fkfDfuQHYrWoytFMVyrL4I9A9FNQ=="}]},"_npmUser":{"name":"muditdixit","email":"muditdixit9352@gmail.com"},"directories":{},"maintainers":[{"name":"muditdixit","email":"muditdixit9352@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aero_0.10.0_1788524129248_0.5856046613148869"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-03T16:52:47.016Z","modified":"2026-09-04T12:15:29.597Z","0.1.0":"2026-09-03T16:52:47.333Z","0.2.0":"2026-09-03T18:55:26.586Z","0.3.0":"2026-09-03T19:14:26.416Z","0.4.0":"2026-09-03T19:18:56.058Z","0.5.0":"2026-09-03T19:25:06.092Z","0.9.0":"2026-09-04T07:28:00.926Z","0.10.0":"2026-09-04T12:15:29.392Z"},"bugs":{"url":"https://github.com/jngjneir/ballastra-backend1/issues"},"license":"MIT","homepage":"https://github.com/jngjneir/ballastra-backend1#readme","keywords":["ballastra","aero","bot","automation","sdk"],"repository":{"type":"git","url":"git+https://github.com/jngjneir/ballastra-backend1.git","directory":"packages/aero-sdk"},"description":"Official SDK for building Ballastra Aeros: connect, handle events and commands, and act, without writing raw Socket.IO or REST.","maintainers":[{"name":"muditdixit","email":"muditdixit9352@gmail.com"}],"readme":"# @ballastra/aero\n\nThe official SDK for building a **Ballastra Aero**: an app that lives inside a Nexus, reacts to events, answers commands, and acts through the permissions a Nexus owner grants.\n\nIt wraps the real Aero contract (gateway + runtime API) so you don't write raw Socket.IO or `fetch` calls, handle reconnects, or de-duplicate deliveries yourself.\n\n## Install\n\n```bash\nnpm install @ballastra/aero\n```\n\n## Quick start\n\n```js\nimport { createAero } from '@ballastra/aero';\n\nconst aero = await createAero({ token: process.env.AERO_TOKEN });\nconsole.log(`Connected as ${aero.aero.name}, installed in ${aero.installations.length} Nexus(es).`);\n\n// Greet every new member in a chosen space.\naero.on('member.joined', async (ev) => {\n  const m = ev.data.member;\n  if (m.is_aero) return;\n  await aero.sendMessage(ev.nexus_id, process.env.WELCOME_SPACE_ID, `Welcome, ${m.name}! 👋`);\n});\n\n// Answer a slash command. `reply()` posts into the space it was run in.\naero.command('welcome', async (i) => {\n  const who = i.options.name || i.invoker.name;\n  await i.reply(`Welcome, ${who}! 👋`);\n});\n```\n\nThat's it. The SDK connects, identifies, re-registers on reconnect, and de-dupes at-least-once deliveries for you.\n\n## API\n\n### `createAero(options)` → `Promise<AeroClient>`\nCreates a client and connects. Same options as `new AeroClient()`.\n\n### `new AeroClient(options)`\n- `token` (required): your Aero token, from the Developer Portal (shown once).\n- `baseUrl`: API + gateway origin. Defaults to production.\n- `dedupeCacheSize`: recent ids remembered for de-duplication (default 500).\n\n### Methods\n- `await client.connect()`: connect + identify. Resolves once ready.\n- `client.on(type, handler)`: handle an event (`member.joined`, `message.created`, `opportunity.created`, and more). Returns an unsubscribe function. `handler(ev)` where `ev = { id, type, nexus_id, space_id?, data }`.\n- `client.command(name, handler)`: handle a slash command. `handler(i)` where `i` includes `command`, `options`, `invoker`, `nexus_id`, `space_id`, and a bound `i.reply(text)`.\n- `client.component(customId, handler)`: handle a button press or select choice by its `custom_id` (`'*'` catches any unmatched one). `handler(i)` includes `type` (`button`/`select`), `custom_id`, `values?`, `invoker`, `message_id`, and a bound `i.reply(...)`.\n- `client.prefix('!')` + `client.prefixCommand(name, handler)`: Discord-classic **prefix commands** (e.g. `!ban @user spam`). Needs the **Read messages** grant + a `message.created` subscription. `handler(ctx)` gets `command`, `args[]`, `text`, `sender_id`, `sender_name`, `space_id`, `nexus_id`, and a bound `ctx.reply(...)`.\n- `await client.sendMessage(nexusId, spaceId, message)`: post a message as the Aero. `message` is a string, or `{ text?, embeds?, components? }` for rich cards + buttons/selects (permission + scope checked server-side).\n- `await client.openModal(nexusId, targetUserId, modal, { spaceId })`: open a form for one user (in response to an interaction). `modal` is `{ title, inputs: [{ label, style?, required? }] }`; the submit arrives as a `modal_submit` interaction with `fields`.\n- `await client.createSpace(nexusId, { name, description?, private? })`: create a space (e.g. a ticket channel). Needs the **Manage spaces** grant. Returns `{ space }`. `private: true` hides it from everyone until members are added.\n- `await client.addSpaceMember(nexusId, spaceId, userId)` / `removeSpaceMember(...)`: add/remove a member of a space the Aero manages (the ticket opener, staff, etc.).\n- `await client.assignRole(nexusId, userId, roleId)` / `removeRole(...)`: give/remove a role below the Aero's own (needs **Manage roles**).\n- `await client.createInvite(nexusId, { expiresInDays, maxUses })`: create an invite link (needs **Create invites**). Returns `{ invite }`.\n- `await client.timeoutMember(nexusId, userId, minutes, reason?)`: mute a member (needs **Moderate chat** + rank above them).\n- `await client.kickMember(nexusId, userId)`: remove a member (needs **Remove members** + rank above them).\n- `await client.banMember(nexusId, userId, reason?)`: ban a member (needs **Ban members** + rank above them).\n- `await client.warnMember(nexusId, userId, reason?)`: issue a warning; returns `{ warnings }` (the new count). Needs **Moderate chat**.\n- `await client.getWarnings(nexusId, userId)` / `clearWarnings(...)`: read / clear a member's warnings.\n- `await client.purgeMessages(nexusId, spaceId, count)`: bulk-delete the most recent 2-100 messages (needs **Manage messages**).\n- `await client.createRole(nexusId, { name, color, permissions })`: create a role below the Aero's own; `permissions[]` is clamped to what the Aero holds (needs **Manage roles**).\n- `await client.createCategory(nexusId, name)`: create a sidebar category (needs **Manage categories**). With `createSpace` this powers auto-setup / server-builder bots.\n- `await client.me()`: refresh identity + installs.\n- `client.onLifecycle('ready' | 'error' | 'disconnect', fn)`: lifecycle hooks.\n- `client.api(path, { method, body })`: low-level runtime call, if you need one.\n- `client.disconnect()`.\n\n### Errors\nRuntime calls throw `AeroError` with a stable `.code` (e.g. `AERO_PERMISSION_DENIED`, `AERO_SCOPE_DENIED`) and `.status`, so you can branch on them.\n\n## Without the SDK\n\nThe SDK is optional. Every call it makes is a public contract. See the in-app **Developer Docs** for the raw gateway + REST version.\n","readmeFilename":"README.md"}