@wavezfm/api 0.1.9 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.3.0
+
+### Added
+
+- Typed room-bot ephemeral chat messages over HTTP and WebSocket.
+- Optional delivery of ephemeral messages to one user ID or up to 50 user IDs.
+- Typed room-bot send-message responses, including persistence and delivery metadata.
+- Canonical documentation links through `https://docs.wavez.fm/docs` package metadata and README navigation.
+
+## 0.2.0
+
+### Added
+
+- Chat image uploads and media previews.
+- External room media validation, metadata, Google Drive helpers, room leave, playback history, deletion, audit-log clearing, and word filters.
+- Playlist search, ordering, availability checks, JSON import/export, track clipping, recent-room filtering, and paginated media search.
+- GIF favorites, Last.fm account flows, Discord role sync, and social-image settings.
+- Subscription management, payment history, miscellaneous checkout, Mercado Pago, and room subscription gifts.
+- Notification center status and clearing.
+- Room-bot word filters and superfans.
+
+### Fixed
+
+- Unwrapped room detail responses so `room.getBySlug()` and slug-based joins return the actual room.
+- Corrected paginated media search, playlist mutation, user settings, and checkout response types to match the server.
+
+### Removed
+
+- Obsolete friend-request methods whose server routes no longer exist. Fan and superfan methods remain under `client.friend` for compatibility.

package/README.md

@@ -1,466 +1,69 @@
 # @wavezfm/api
 
-Official JavaScript/TypeScript API client for WavezFM.
+Official fetch-based JavaScript and TypeScript client for WavezFM. The package ships with zero runtime dependencies.
 
-This package is fetch-based and ships with zero runtime dependencies.
+## Documentation
+
+The canonical documentation is hosted at [docs.wavez.fm](https://docs.wavez.fm/docs).
+
+- [Getting started](https://docs.wavez.fm/docs/getting-started)
+- [Frontend API](https://docs.wavez.fm/docs/frontend-api)
+- [SDK reference](https://docs.wavez.fm/docs/sdk)
+- [Room bots](https://docs.wavez.fm/docs/room-bots)
+- [Room Bot HTTP API](https://docs.wavez.fm/docs/room-bots/http-api)
+- [Room Bot Realtime API](https://docs.wavez.fm/docs/room-bots/realtime)
 
 ## Installation
 
 ```bash
-npm install @wavezfm/api
-# or
-yarn add @wavezfm/api
-# or
 bun add @wavezfm/api
 ```
 
-## Quick Start
-
-```ts
-import { createApiClient } from "@wavezfm/api";
-
-const client = createApiClient({
-  baseURL: "https://api.wavez.fm",
-});
-
-const rooms = await client.room.list();
-console.log(rooms.data);
+```bash
+npm install @wavezfm/api
 ```
 
-## Configuration
+## Quick start
 
 ```ts
-createApiClient({
-  baseURL: "https://api.wavez.fm",
-  timeout: 15_000,
-  logging: false,
-  headers: { "X-App-Version": "1.0.0" },
-  credentials: "include",
-  locale: "en",
-});
-```
-
-The client accepts:
-
-- `https://api.wavez.fm`
-
-If you use a dedicated API origin such as `api.wavez.fm`, 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.fm",
-  locale: "en",
-  messages: {
-    roomBotCreatePrefixLengthInvalid: "Custom prefix length message.",
-  },
-});
-```
-
-## API Surfaces
-
-This SDK exposes three distinct surfaces. They do not authenticate the same way.
-
-### Site / Browser API
-
-Use this for the normal site routes:
-
-- auth
-- settings
-- users
-- rooms
-- playlists
-- chat
-- billing
-- shop
-
-Auth mode:
-
-- browser session cookies
-- same protections used by the site
-
-This is also where bot tokens are created with `client.room.createBotToken(...)`.
-
-### Room Bot HTTP API
-
-Use this for backend automation scoped to one room:
-
-- room state
-- room event history
-- bot chat send/read
-- queue actions
-- moderation and room management
-
-Auth mode:
-
-- room bot token with `client.api.setRoomBotToken(...)`
-
-### Room Bot Realtime API
-
-Use this for low-latency bot behavior:
+import { createApiClient } from '@wavezfm/api';
 
-- chat listeners
-- queue/playback/vote listeners
-- command reactions
-
-Auth mode:
-
-- room bot token over WebSocket
-
-## Site / Browser API
-
-WavezFM uses session cookies for most user-authenticated routes.
-
-```ts
 const client = createApiClient({
-  baseURL: "https://api.wavez.fm",
-});
-
-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 integrations, prefer the room-bot surfaces below. Regular user routes are browser-first.
-
-### Site Resources
-
-All site resources are exposed from the pre-configured client:
-
-```ts
-const client = createApiClient({ baseURL: "https://api.wavez.fm" });
-```
-
-#### Auth
-
-```ts
-await client.auth.login({ email, password });
-await client.auth.register({ email, password, name, username });
-const me = await client.auth.me();
-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("wavezfm-lounge");
-await client.room.getWaitlist("wavezfm-lounge");
-await client.room.create({ slug: "my-room", name: "My Room" });
-await client.room.join("wavezfm-lounge");
-await client.room.favorite("room-id");
-await client.room.getManagement("room-id");
-```
-
-#### 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("wavezfm-lounge", 0, 50);
-await client.chat.updateMessage("room-id", "message-id", {
-  content: "edited message",
+  baseURL: 'https://api.wavez.fm',
 });
-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();
+const rooms = await client.room.list();
+console.log(rooms.data);
 ```
 
-#### System
+## Room bot quick start
 
 ```ts
-await client.system.status();
-await client.system.publicStats();
-await client.system.health();
-```
-
-## Room Bot HTTP API
-
-Room bot tokens are created from the site/session surface, then used on the bot surface.
+import { createApiClient } from '@wavezfm/api';
 
-```ts
 const client = createApiClient({
-  baseURL: "https://api.wavez.fm",
-});
-
-const created = await client.room.createBotToken("room-id", {
-  botName: "Night Shift Bot",
-  commandPrefix: "!",
-  permissions: [
-    "read_state",
-    "read_chat",
-    "send_chat",
-    "manage_queue",
-    "skip_others",
-    "mute_user",
-    "kick_user",
-    "ban_user",
-    "clear_chat",
-    "manage_room",
-  ],
-});
-
-const roomBotToken = created.data.token;
-
-// Store this in your backend or environment store.
-client.api.setRoomBotToken(roomBotToken);
-```
-
-Important:
-
-- the plain bot token is returned by `client.room.createBotToken(...)`
-- it is only available in that creation response
-- store it securely on your backend after creation
-- later, load it back with `client.api.setRoomBotToken(...)`
-- `manage_room` works as a broad administrative permission; granular permissions such as `manage_queue`, `ban_user`, and `clear_chat` can be used when the bot should be narrower
-
-### Bot Resources
-
-```ts
-client.api.setRoomBotToken(process.env.WAVEZ_ROOM_BOT_TOKEN!);
-
-await client.roomBot.getState("room-id");
-await client.roomBot.getQueueStatus("room-id");
-await client.roomBot.getMessages("room-id");
-await client.roomBot.getEvents("room-id", {
-  limit: 25,
-  types: ["user_joined", "waitlist_join", "left"],
-});
-await client.roomBot.addToQueue("room-id", "user-id");
-await client.roomBot.sendMessage("room-id", {
-  content: "!lockqueue",
+  baseURL: 'https://api.wavez.fm',
+  roomBotToken: process.env.WAVEZFM_ROOM_BOT_TOKEN,
 });
-await client.roomBot.editMessage("room-id", "message-id", {
-  content: "!lockqueue agora",
-});
-await client.roomBot.updateSettings("room-id", {
-  queueLocked: true,
-  commandAnnouncement: {
-    commandId: "lockqueue",
-    actorUsername: "Night Shift Bot",
-  },
-});
-
-const state = await client.roomBot.getState("room-id");
-console.log(state.data.room?.description);
-console.log(state.data.currentUser?.globalRole);
-console.log(state.data.currentUser?.roomRole);
-```
-
-`roomBot.getEvents()` is the normalized HTTP history surface.
-
-Returned `event` values:
-
-- `user_joined`
-- `waitlist_join`
-- `left`
-
-Accepted filter aliases in `types` for backward compatibility:
-
-- `queue_joined` -> `waitlist_join`
-- `user_left` -> `left`
-
-## Room Bot Realtime API
 
-```ts
-import {
-  createRoomBotRealtimeClient,
-  formatMentionText,
-} from "@wavezfm/api";
-
-const bot = createRoomBotRealtimeClient({
-  baseURL: "https://api.wavez.fm",
-  botToken: process.env.WAVEZ_ROOM_BOT_TOKEN!,
-  roomId: "room-id",
-  locale: "en",
-  autoReconnect: true,
-});
-
-bot.on("message_created", (packet) => {
-  console.log(packet.payload);
-});
+const state = await client.roomBot.getState('room-id');
+console.log(state.data.room);
 
-bot.on("queue_joined", (packet) => {
-  console.log(packet.payload);
-});
-
-await bot.connect();
-bot.sendChat({
-  content: `${formatMentionText("Agente MIB")} estou em modo AFK agora.`,
+await client.roomBot.sendMessage('room-id', {
+  content: 'This live notice is not stored in chat history.',
+  ephemeral: true,
 });
 ```
 
-The realtime helper automatically retries abnormal disconnects such as WebSocket close code `1006` by default. Fatal closes like revoked or invalid auth are not retried.
-
-Important:
-
-- realtime packet names are the raw WebSocket event names
-- examples: `message_created`, `user_left`, `queue_joined`, `track_started`
-- they are not normalized to the HTTP history names
-
-## Error Handling
+Room-bot tokens are backend credentials. Never expose them in browser code, public logs, or client-side storage.
 
-All methods throw `ApiError` on failure.
+## Build locally
 
-```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://api.wavez.fm" });
-
-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://api.wavez.fm" });
-const room = createRoomResource(api);
-const roomBot = createRoomBotResource(api);
-```
-
-## TypeScript
-
-```ts
-import type {
-  AuthUser,
-  RoomSummary,
-  PlaylistTrack,
-  MediaSearchResult,
-  ChatMessage,
-  RoomBotState,
-  RoomPresenceEventType,
-  RoomPresenceEventFilterType,
-  WsPacket,
-} from "@wavezfm/api";
+```bash
+npm run typecheck
+npm run build
 ```
 
-## Notes
+## License
 
-- site/session routes are browser-first because the backend uses cookies and same-origin protections
-- room-bot HTTP routes are backend-first and scoped to one room
-- room-bot realtime uses raw WebSocket packet names
-- the package is tree-shakable through factory exports in `resources/*`
-- the realtime helper expects native `WebSocket` or a custom `websocketFactory`
+MIT