aegis-api 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mubi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,230 @@
-# Temporary Holding Version
+# aegis.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/AegisAPI/aegis.js/actions/workflows/ci.yml/badge.svg)](https://github.com/AegisAPI/aegis.js/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/aegis.js)](https://www.npmjs.com/package/aegis.js)
+
+The official TypeScript client for the [Aegis](https://aegi.run) API: music, images, games and utilities for a Discord bot, so you do not have to build any of it yourself.
+
+Every route, parameter, body and response is typed from the API's OpenAPI document. Successful responses arrive already unwrapped, and anything the API rejects arrives as an `AegisError`.
+
+- Typed methods for all 38 `/v1` routes.
+- Zero runtime dependencies.
+- ESM only, ships type declarations.
+- A typed WebSocket client for the music events.
+
+## Install
+
+```sh
+npm install @aegis-api/aegis.js
+```
+
+Needs a runtime with a global `fetch` (Node 18+). The event socket also needs a global `WebSocket` (Node 22+), unless you supply your own.
+
+## Quick start
+
+```ts
+import { Aegis } from 'aegis-api'
+
+const aegis = new Aegis({ apiKey: process.env.AEGIS_API_KEY })
+
+// Play whatever the query finds, joining the caller's channel.
+const { track, position } = await aegis.music.play(guildId, {
+  query: 'lofi hip hop',
+  channelId: voiceChannelId,
+})
+
+// Search first, then play exactly what was picked.
+const found = await aegis.music.search({ query: 'rick astley', limit: 5 })
+const chosen = found.results[0]!
+await aegis.music.play(guildId, { track: { encoded: chosen.encoded } })
+
+// Read the player: what is playing, where playback is, and the queue.
+const state = await aegis.music.queue(guildId)
+console.log(state.current?.title, state.volume, state.loop)
+```
+
+## API key
+
+Create a key on [aegi.run](https://aegi.run) and pass it as `apiKey`. It is sent as `Authorization: Bearer <key>` on every request, and as a header on the event socket handshake.
+
+`apiKey` and `baseUrl` cannot both be omitted. Constructing a client with neither throws right away instead of failing on the first call.
+
+## Options
+
+Every option goes to the constructor.
+
+| Option         | Type                              | Default                | Notes                                                  |
+| -------------- | --------------------------------- | ---------------------- | ------------------------------------------------------ |
+| `apiKey`       | `string`                          | `undefined`            | Sent as a bearer token.                                |
+| `baseUrl`      | `string`                          | `https://api.aegi.run` | Trailing slashes are trimmed.                          |
+| `timeoutMs`    | `number`                          | `30000`                | Per request, via `AbortSignal.timeout`.                |
+| `fetch`        | `typeof globalThis.fetch`         | `globalThis.fetch`     | Inject your own for tests, proxies or instrumentation. |
+| `userAgent`    | `string`                          | `aegis.js`             |                                                        |
+| `createSocket` | `(url, headers) => WebSocketLike` | global `WebSocket`     | Inject a socket implementation.                        |
+
+## Resources
+
+Resources hang off the client, grouped the way the API groups them.
+
+- `aegis.music`: `search` `play` `pause` `resume` `skip` `stop` `queue` `clearQueue` `volume` `setVolume` `mute` `unmute` `seek` `shuffle` `restart` `loop` `setLoop` `removeFromQueue` `moveInQueue`
+- `aegis.minecraft`: `info` `textures` `render`
+- `aegis.jobs`: `get` `wait`
+- `aegis.bible`: `languages` `types` `translations` `books` `chapter` `search` `verses` `data`
+- `aegis.binary`: `encode` `decode`
+- `aegis.translation`: `translate` `detect` `languages`
+- `aegis.roblox`: `user` `game`
+- `aegis.holidays`: `next` `year`
+- `aegis.fun`: `roleplay`
+- `aegis.general`: `status`
+
+A few of them in full:
+
+```ts
+await aegis.music.setVolume(guildId, { volume: 40, muted: true }) // 100 is default, 200 the highest
+await aegis.music.seek(guildId, { position: 30_000 })
+await aegis.music.setLoop(guildId, { mode: 'queue' }) // 'off' | 'track' | 'queue'
+await aegis.music.moveInQueue(guildId, 3, { to: 0 })
+
+await aegis.translation.translate({ text: 'hello', to: 'pt' })
+await aegis.bible.verses('bbe', { refs: 'John 3:16' })
+await aegis.holidays.next('BR')
+await aegis.roblox.game(107778070777162)
+await aegis.binary.encode({ text: 'hello' })
+await aegis.fun.roleplay({ type: 'hug' })
+```
+
+### Jobs
+
+Routes that queue work answer with a job instead of a result. Renders are the common case.
+
+```ts
+const queued = await aegis.minecraft.render('Notch', {
+  render: 'wave',
+  scale: 4,
+})
+
+// Poll it...
+const job = await aegis.jobs.get(queued.jobId)
+
+// ...or hold the request open until it reaches a final state.
+const finished = await aegis.jobs.wait(queued.jobId, { timeout: 60 })
+if (finished.status === 'completed') console.log(finished.result)
+```
+
+## Events
+
+`aegis.music` also exposes the event socket, typed per event name.
+
+```ts
+const off = aegis.music.on('trackStarted', (event) => {
+  console.log(`${event.track.title} in ${event.guildId}`)
+})
+
+aegis.music.once('trackEnded', (event) => console.log(event.reason))
+
+off() // the return value unsubscribes
+```
+
+| Event          | Payload                                                   |
+| -------------- | --------------------------------------------------------- |
+| `trackStarted` | `botId` `guildId` `track`                                 |
+| `trackEnded`   | `botId` `guildId` `reason`                                |
+| `queueEmptied` | `botId` `guildId`                                         |
+| `playerClosed` | `botId` `guildId` `reason` (`'idle'` or `'disconnected'`) |
+| `botStopped`   | `botId` `reason`                                          |
+
+`MUSIC_EVENTS` lists the same names as a runtime value.
+
+How the socket behaves:
+
+- It opens on the first listener and closes when the last one unsubscribes, so a bot that never listens never holds a connection.
+- It reconnects 5 seconds after an unexpected close, as long as someone is still listening.
+- `ready` and `ping` frames, and events nobody subscribed to, are ignored.
+- A listener that throws is logged; the others still run.
+
+`aegis.music.listening` reports whether the socket is open. `aegis.music.disconnect()` closes it for good.
+
+## Errors
+
+Every non-2xx answer, and any request that never left the machine, throws an `AegisError`.
+
+```ts
+import { AegisError } from 'aegis-api'
+
+try {
+  await aegis.music.play(guildId, { query: 'lofi' })
+} catch (error) {
+  if (error instanceof AegisError) {
+    error.status // 403
+    error.code // 'forbidden'
+    error.requestId // quote this when asking for help
+    error.body // the parsed error envelope
+  }
+}
+```
+
+## Any route, by path
+
+Routes without a named method are still reachable, and still typed.
+
+```ts
+const status = await aegis.request('get', '/v1/status')
+//    ^? the exact shape the API documents
+
+await aegis.request('post', '/v1/music/guilds/{guildId}/play', {
+  params: { guildId },
+  body: { query: 'lofi' },
+})
+
+// @ts-expect-error /v1/status takes no query
+await aegis.request('get', '/v1/status', { query: { a: 1 } })
+
+// @ts-expect-error /v1/status has no patch
+await aegis.request('patch', '/v1/status')
+```
+
+## Types
+
+The response shapes are re-exported under readable names, so you rarely need to reach into the schema namespace.
+
+```ts
+import type {
+  Job,
+  PlayerState,
+  PlayResult,
+  Track,
+  components,
+  PathKey,
+  Paths,
+  RequestOptions,
+  Result,
+} from 'aegis-api'
+```
+
+`components` is the whole OpenAPI `components` namespace, so any schema in the document is reachable from there.
+
+## Development
+
+```sh
+git clone https://github.com/AegisAPI/aegis.js
+cd aegis.js
+bun install
+
+bun test # unit tests
+bun run typecheck # tsc --noEmit
+bun run build # emit dist/ with type declarations
+bun run format # prettier
+bun run schema:build # regenerate src/generated/schema.ts from the live spec
+```
+
+`schema:build` rewrites the generated types from `https://api.aegi.run/openapi.json`, so route types follow the API rather than this repository. After regenerating, run typecheck: a path or field the API renamed shows up there first.
+
+CI runs typecheck, tests, build and the format check on every push and pull request.
+
+## Contributing
+
+Keep a pull request focused on one thing, and leave `bun run typecheck`, `bun test` and `bun run format:check` green.
+
+## License
+
+[MIT](./LICENSE) © 2026 Mubi

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import { Http, type HttpOptions } from './http.js';
+import { BibleResource, BinaryResource, FunResource, GeneralResource, HolidaysResource, JobsResource, MinecraftResource, MusicResource, RobloxResource, TranslationResource } from './resources/index.js';
+import type { HttpMethod, MethodOf, PathKey, RequestOptions, Result } from './types.js';
+export interface AegisOptions extends HttpOptions {
+}
+export declare class Aegis {
+    readonly http: Http;
+    readonly music: MusicResource;
+    readonly minecraft: MinecraftResource;
+    readonly jobs: JobsResource;
+    readonly bible: BibleResource;
+    readonly binary: BinaryResource;
+    readonly translation: TranslationResource;
+    readonly roblox: RobloxResource;
+    readonly holidays: HolidaysResource;
+    readonly fun: FunResource;
+    readonly general: GeneralResource;
+    constructor(options?: AegisOptions);
+    /** Escape hatch for the routes without a named method yet. */
+    request<P extends PathKey, M extends HttpMethod>(method: M & MethodOf<NoInfer<P>>, path: P, options?: RequestOptions<P, M>): Promise<Result<P, M>>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAoB,MAAM,WAAW,CAAA;AACpE,OAAO,EACL,aAAa,EACb,cAAc,EACd,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,mBAAmB,EACpB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EACV,UAAU,EACV,QAAQ,EACR,OAAO,EACP,cAAc,EACd,MAAM,EACP,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,YAAa,SAAQ,WAAW;CAAG;AAEpD,qBAAa,KAAK;IAChB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;IACrC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAA;IACzC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;gBAErB,OAAO,GAAE,YAAiB;IAqBtC,8DAA8D;IAC9D,OAAO,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,UAAU,EAC7C,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAChC,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7B,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAKzB"}

package/dist/client.js

@@ -0,0 +1,37 @@
+import { AegisError } from './errors.js';
+import { Http } from './http.js';
+import { BibleResource, BinaryResource, FunResource, GeneralResource, HolidaysResource, JobsResource, MinecraftResource, MusicResource, RobloxResource, TranslationResource, } from './resources/index.js';
+export class Aegis {
+    http;
+    music;
+    minecraft;
+    jobs;
+    bible;
+    binary;
+    translation;
+    roblox;
+    holidays;
+    fun;
+    general;
+    constructor(options = {}) {
+        if (options.baseUrl === undefined && options.apiKey === undefined) {
+            throw new AegisError('Aegis needs an apiKey, or at least an explicit baseUrl.', { status: 0, code: 'bad_request' });
+        }
+        this.http = new Http(options);
+        this.music = new MusicResource(this.http, options);
+        this.minecraft = new MinecraftResource(this.http);
+        this.jobs = new JobsResource(this.http);
+        this.bible = new BibleResource(this.http);
+        this.binary = new BinaryResource(this.http);
+        this.translation = new TranslationResource(this.http);
+        this.roblox = new RobloxResource(this.http);
+        this.holidays = new HolidaysResource(this.http);
+        this.fun = new FunResource(this.http);
+        this.general = new GeneralResource(this.http);
+    }
+    /** Escape hatch for the routes without a named method yet. */
+    request(method, path, options) {
+        return this.http.send(method, path, options);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,IAAI,EAAsC,MAAM,WAAW,CAAA;AACpE,OAAO,EACL,aAAa,EACb,cAAc,EACd,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,mBAAmB,GACpB,MAAM,sBAAsB,CAAA;AAW7B,MAAM,OAAO,KAAK;IACP,IAAI,CAAM;IACV,KAAK,CAAe;IACpB,SAAS,CAAmB;IAC5B,IAAI,CAAc;IAClB,KAAK,CAAe;IACpB,MAAM,CAAgB;IACtB,WAAW,CAAqB;IAChC,MAAM,CAAgB;IACtB,QAAQ,CAAkB;IAC1B,GAAG,CAAa;IAChB,OAAO,CAAiB;IAEjC,YAAY,UAAwB,EAAE;QACpC,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAClE,MAAM,IAAI,UAAU,CAClB,yDAAyD,EACzD,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CACnC,CAAA;QACH,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAA;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QAClD,IAAI,CAAC,SAAS,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjD,IAAI,CAAC,IAAI,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACvC,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACzC,IAAI,CAAC,MAAM,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC3C,IAAI,CAAC,WAAW,GAAG,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACrD,IAAI,CAAC,MAAM,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC3C,IAAI,CAAC,QAAQ,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC/C,IAAI,CAAC,GAAG,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACrC,IAAI,CAAC,OAAO,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/C,CAAC;IAED,8DAA8D;IAC9D,OAAO,CACL,MAAgC,EAChC,IAAO,EACP,OAA8B;QAE9B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,OAAsB,CAEzD,CAAA;IACH,CAAC;CACF"}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+import type { components } from './generated/schema.js';
+export type ApiErrorCode = components['schemas']['ErrorResponse']['error']['code'];
+export type ErrorResponse = components['schemas']['ErrorResponse'];
+export interface AegisErrorOptions {
+    status: number;
+    code: ApiErrorCode | string;
+    requestId?: string;
+    body?: unknown;
+}
+/** Thrown for any non-2xx answer, and for a request that never left the box. */
+export declare class AegisError extends Error {
+    readonly status: number;
+    readonly code: ApiErrorCode | string;
+    readonly requestId: string | undefined;
+    readonly body: unknown;
+    constructor(message: string, options: AegisErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAEvD,MAAM,MAAM,YAAY,GACtB,UAAU,CAAC,SAAS,CAAC,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAA;AAEzD,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,eAAe,CAAC,CAAA;AAElE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,YAAY,GAAG,MAAM,CAAA;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,gFAAgF;AAChF,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAAA;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;gBAEV,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB;CAQxD"}

package/dist/errors.js

@@ -0,0 +1,16 @@
+/** Thrown for any non-2xx answer, and for a request that never left the box. */
+export class AegisError extends Error {
+    status;
+    code;
+    requestId;
+    body;
+    constructor(message, options) {
+        super(message);
+        this.name = 'AegisError';
+        this.status = options.status;
+        this.code = options.code;
+        this.requestId = options.requestId;
+        this.body = options.body;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAcA,gFAAgF;AAChF,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,MAAM,CAAQ;IACd,IAAI,CAAuB;IAC3B,SAAS,CAAoB;IAC7B,IAAI,CAAS;IAEtB,YAAY,OAAe,EAAE,OAA0B;QACrD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,YAAY,CAAA;QACxB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAA;QACxB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAA;QAClC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAA;IAC1B,CAAC;CACF"}