@wavezfm/api 0.1.0

package/README.md

@@ -0,0 +1,338 @@
+# @wavezfm/api
+
+Official JavaScript/TypeScript API client for Wavez.
+
+This package is fetch-based and ships with zero runtime dependencies.
+
+## Installation
+
+```bash
+npm install @wavezfm/api
+```
+
+## Quick Start
+
+```ts
+import { createApiClient } from '@wavezfm/api';
+
+const client = createApiClient({
+  baseURL: 'https://api.wavez.example.com',
+});
+
+const rooms = await client.room.list();
+console.log(rooms.data);
+```
+
+## Configuration
+
+```ts
+createApiClient({
+  baseURL: 'https://api.wavez.example.com', // required
+  timeout: 15_000,                              // optional, default: 30000
+  logging: false,                               // optional
+  headers: { 'X-App-Version': '1.0.0' },        // optional
+  credentials: 'include',                       // optional, default: include
+  locale: 'en',                                 // optional, default: en
+})
+```
+
+The client accepts either:
+
+- `https://api.wavez.example.com`
+- `https://wavez.example.com/api`
+- `https://wavez.example.com`
+
+If you use a dedicated API origin such as `api.wavez.example.com`, the SDK keeps root paths like `/rooms`.
+If you pass the main site origin, the SDK still falls back to `/api`.
+
+You can localize SDK-generated errors with `locale` or override specific messages with `messages`:
+
+```ts
+const client = createApiClient({
+  baseURL: 'https://api.wavez.example.com',
+  locale: 'en',
+  messages: {
+    roomBotCreatePrefixLengthInvalid: 'Custom prefix length message.',
+  },
+});
+```
+
+## Browser Session Auth
+
+Wavez uses session cookies for most user-authenticated routes.
+
+```ts
+const client = createApiClient({
+  baseURL: 'https://wavez.example.com/api',
+});
+
+await client.auth.login({
+  email: 'user@example.com',
+  password: 'secret',
+});
+
+const me = await client.auth.me();
+if (me.data) {
+  console.log(me.data.displayUsername ?? me.data.username);
+}
+```
+
+For server-side Node integrations, room-bot routes are the best fit. Regular user routes rely on the browser session/cookie flow used by the site.
+
+## Room Bots
+
+```ts
+const client = createApiClient({
+  baseURL: 'https://wavez.example.com/api',
+});
+
+client.api.setRoomBotToken(process.env.WAVEZ_ROOM_BOT_TOKEN!);
+
+const state = await client.roomBot.getState('room-id');
+console.log(state.data.bot);
+```
+
+## Realtime Room Bots
+
+```ts
+import { createRoomBotRealtimeClient } from '@wavezfm/api';
+
+const bot = createRoomBotRealtimeClient({
+  baseURL: 'https://wavez.example.com/api',
+  botToken: process.env.WAVEZ_ROOM_BOT_TOKEN!,
+  roomId: 'room-id',
+  locale: 'en',
+});
+
+bot.on('message_created', (packet) => {
+  console.log(packet.payload);
+});
+
+await bot.connect();
+```
+
+## Resources
+
+All resources are exposed from the pre-configured client:
+
+```ts
+const client = createApiClient({ baseURL: 'https://wavez.example.com/api' });
+```
+
+### Auth
+
+```ts
+await client.auth.login({ email, password });
+await client.auth.register({ email, password, name, username });
+const me = await client.auth.me(); // returns `null` in `data` when there is no active session
+await client.auth.getPendingTwoFactor();
+await client.auth.sendPendingTwoFactorCode();
+await client.auth.verifyPendingTwoFactor({ code: '123456' });
+```
+
+### Settings
+
+```ts
+await client.settings.get();
+await client.settings.update({
+  bio: 'Late-night selector',
+  presenceStatus: 'busy',
+  showChatBadge: true,
+});
+await client.settings.getTwoFactor();
+await client.settings.startEmailTwoFactor({ password: 'secret' });
+await client.settings.startAuthenticatorTwoFactor({ password: 'secret' });
+await client.settings.disableTwoFactor({ password: 'secret' });
+```
+
+### Users
+
+```ts
+await client.user.getById('user-id');
+await client.user.getByUsername('haru');
+await client.user.getBadges('user-id');
+await client.user.listAllBadges();
+```
+
+### Rooms
+
+```ts
+await client.room.list();
+await client.room.featured();
+await client.room.getBySlug('wavez-lounge');
+await client.room.getWaitlist('wavez-lounge');
+await client.room.create({ slug: 'my-room', name: 'My Room' });
+await client.room.join('wavez-lounge');
+await client.room.favorite('room-id');
+await client.room.getManagement('room-id');
+await client.room.createBotToken('room-id', {
+  botName: 'Night Shift Bot',
+  commandPrefix: '!',
+  permissions: ['read_state', 'read_chat', 'send_chat', 'manage_room'],
+});
+```
+
+### Playlists
+
+```ts
+await client.playlist.list();
+await client.playlist.create('My Playlist');
+await client.playlist.update('playlist-id', { name: 'Late Night Set' });
+await client.playlist.getTracks('playlist-id');
+await client.playlist.previewUrl('https://youtube.com/watch?v=dQw4w9WgXcQ');
+await client.playlist.addTrack('playlist-id', {
+  source: 'youtube',
+  sourceId: 'dQw4w9WgXcQ',
+});
+await client.playlist.reorderTracks('playlist-id', ['track-a', 'track-b']);
+await client.playlist.startSpotifyImport({
+  playlistId: 'playlist-id',
+  url: 'https://open.spotify.com/playlist/...',
+});
+```
+
+### Sources
+
+```ts
+await client.source.searchYouTube('lofi hip hop', 10);
+await client.source.searchSoundCloud('nightcore', 10);
+await client.source.searchAll('ambient');
+```
+
+### Chat
+
+```ts
+await client.chat.getMessages('room-id', 0, 50);
+await client.chat.getMessagesBySlug('wavez-lounge', 0, 50);
+await client.chat.updateMessage('room-id', 'message-id', {
+  content: 'edited message',
+});
+await client.chat.pinMessage('room-id', 'message-id');
+await client.chat.clearChat('room-id');
+```
+
+### Friends / Fans
+
+```ts
+await client.friend.list();
+await client.friend.pending();
+await client.friend.sendRequest('user-id');
+await client.friend.acceptRequest('request-id');
+await client.friend.follow('user-id');
+await client.friend.followers();
+```
+
+### Shop
+
+```ts
+await client.shop.getCatalog();
+await client.shop.getWallet();
+await client.shop.purchase({ itemId: 'badge-id' });
+await client.shop.equip('avatar-id');
+await client.shop.getInventory();
+```
+
+### Billing
+
+```ts
+await client.billing.createSubscriptionCheckout({ cycle: 'monthly' });
+await client.billing.createDiamondCheckout({ quantity: 1000 });
+await client.billing.createRoomDonationCheckout('room-id', { amountCents: 500 });
+await client.billing.createGlobalDonationCheckout({ amountCents: 1000 });
+await client.billing.createDiamondGiftCheckout({
+  recipientUsername: 'haru',
+  quantity: 500,
+});
+await client.billing.listPendingGifts();
+```
+
+### System
+
+```ts
+await client.system.status();
+await client.system.publicStats();
+await client.system.health();
+```
+
+### Room Bots
+
+```ts
+client.api.setRoomBotToken(process.env.WAVEZ_ROOM_BOT_TOKEN!);
+
+await client.roomBot.getState('room-id');
+await client.roomBot.getMessages('room-id');
+await client.roomBot.sendMessage('room-id', { content: '!lockqueue' });
+await client.roomBot.updateSettings('room-id', {
+  queueLocked: true,
+  commandAnnouncement: {
+    commandId: 'lockqueue',
+    actorUsername: 'Night Shift Bot',
+  },
+});
+```
+
+## Error Handling
+
+All methods throw `ApiError` on failure.
+
+```ts
+import { ApiError } from '@wavezfm/api';
+
+try {
+  await client.auth.login({ email: 'bad@example.com', password: 'bad' });
+} catch (error) {
+  if (error instanceof ApiError) {
+    console.log(error.message);
+    console.log(error.status);
+    console.log(error.code);
+    console.log(error.response);
+  }
+}
+```
+
+## Token Management
+
+```ts
+const client = createApiClient({ baseURL: 'https://wavez.example.com/api' });
+
+client.api.setAuthToken('optional-bearer-token');
+client.api.setRoomBotToken(process.env.WAVEZ_ROOM_BOT_TOKEN!);
+
+client.api.getAuthToken();
+client.api.getRoomBotToken();
+```
+
+## Tree-Shaking
+
+For maximum tree-shaking, import only what you need:
+
+```ts
+import { createApi } from '@wavezfm/api';
+import { createRoomResource } from '@wavezfm/api/resources/room';
+import { createRoomBotResource } from '@wavezfm/api/resources/room-bot';
+
+const api = createApi({ baseURL: 'https://wavez.example.com/api' });
+const room = createRoomResource(api);
+const roomBot = createRoomBotResource(api);
+```
+
+## TypeScript
+
+```ts
+import type {
+  AuthUser,
+  RoomSummary,
+  PlaylistTrack,
+  MediaSearchResult,
+  ChatMessage,
+  RoomBotState,
+  WsPacket,
+} from '@wavezfm/api';
+```
+
+## Notes
+
+- user/session routes are browser-first because the backend uses cookies and same-origin protections
+- room-bot routes are ideal for backend integrations and automation
+- the package is tree-shakable through factory exports in `resources/*`
+- the realtime helper expects native `WebSocket` or a custom `websocketFactory`

package/dist/core/ApiError.d.ts

@@ -0,0 +1,14 @@
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly code: string | null;
+    readonly response: unknown;
+    readonly headers: Headers;
+    constructor(message: string, input: {
+        status: number;
+        statusText?: string;
+        code?: string | null;
+        response?: unknown;
+        headers?: Headers;
+    });
+}

package/dist/core/ApiError.js

@@ -0,0 +1,20 @@
+export class ApiError extends Error {
+    status;
+    statusText;
+    code;
+    response;
+    headers;
+    constructor(message, input) {
+        super(message);
+        this.name = "ApiError";
+        this.status = input.status;
+        this.statusText = input.statusText ?? "";
+        this.code =
+            typeof input.code === "string" && input.code.trim().length > 0
+                ? input.code
+                : null;
+        this.response = input.response ?? null;
+        this.headers = input.headers ?? new Headers();
+    }
+}
+//# sourceMappingURL=ApiError.js.map

package/dist/core/ApiError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiError.js","sourceRoot":"","sources":["../../src/core/ApiError.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,QAAS,SAAQ,KAAK;IACtB,MAAM,CAAS;IACf,UAAU,CAAS;IACnB,IAAI,CAAgB;IACpB,QAAQ,CAAU;IAClB,OAAO,CAAU;IAE1B,YACI,OAAe,EACf,KAMC;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC;QACzC,IAAI,CAAC,IAAI;YACL,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;gBAC1D,CAAC,CAAC,KAAK,CAAC,IAAI;gBACZ,CAAC,CAAC,IAAI,CAAC;QACf,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC;QACvC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,IAAI,OAAO,EAAE,CAAC;IAClD,CAAC;CACJ"}

package/dist/core/api.d.ts

@@ -0,0 +1,27 @@
+import type { ApiClientConfig, ApiLike, ApiRequestOptions, ApiSuccessResponse, WavezApiMessageKey, WavezApiMessageValues } from "../types";
+export declare class WavezApi implements ApiLike {
+    private readonly baseURL;
+    private readonly defaultHeaders;
+    private readonly timeout;
+    private readonly credentials;
+    private readonly fetchImpl;
+    private readonly logging;
+    private readonly messageFormatter;
+    private authToken;
+    private roomBotToken;
+    constructor(config: ApiClientConfig);
+    getBaseURL(): string;
+    getSiteURL(path?: string): string;
+    formatMessage(key: WavezApiMessageKey, values?: WavezApiMessageValues): string;
+    setAuthToken(token: string | null): void;
+    getAuthToken(): string | null;
+    setRoomBotToken(token: string | null): void;
+    getRoomBotToken(): string | null;
+    request<T, TBody = unknown>(options: ApiRequestOptions<TBody>): Promise<ApiSuccessResponse<T>>;
+    get<T>(path: string, options?: Omit<ApiRequestOptions<never>, "path" | "method" | "body">): Promise<ApiSuccessResponse<T>>;
+    post<T, TBody = unknown>(path: string, body?: TBody, options?: Omit<ApiRequestOptions<TBody>, "path" | "method" | "body">): Promise<ApiSuccessResponse<T>>;
+    put<T, TBody = unknown>(path: string, body?: TBody, options?: Omit<ApiRequestOptions<TBody>, "path" | "method" | "body">): Promise<ApiSuccessResponse<T>>;
+    patch<T, TBody = unknown>(path: string, body?: TBody, options?: Omit<ApiRequestOptions<TBody>, "path" | "method" | "body">): Promise<ApiSuccessResponse<T>>;
+    delete<T, TBody = unknown>(path: string, options?: Omit<ApiRequestOptions<TBody>, "path" | "method">): Promise<ApiSuccessResponse<T>>;
+}
+export declare function createApi(config: ApiClientConfig): WavezApi;