privage.js 0.21.0

package/dist/structures/Message.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Message = exports.TextChannel = void 0;
+const Member_1 = require("./Member");
+const Channel_1 = require("./Channel");
+Object.defineProperty(exports, "TextChannel", { enumerable: true, get: function () { return Channel_1.TextChannel; } });
+function parseAuthor(a) {
+    return {
+        id: String(a?.id ?? ''),
+        username: a?.username ?? 'unknown',
+        displayName: a?.display_name ?? null,
+        avatarUrl: a?.avatar_url ?? null,
+        bot: a?.type === 'bot',
+    };
+}
+function parseAttachment(a) {
+    return {
+        id: String(a?.id ?? ''),
+        filename: a?.filename ?? '',
+        url: a?.url ?? '',
+        mimeType: a?.mime_type ?? '',
+        size: Number(a?.size || 0),
+        width: a?.width != null ? Number(a.width) : null,
+        height: a?.height != null ? Number(a.height) : null,
+        spoiler: a?.spoiler === true,
+        createdAt: a?.created_at ? new Date(a.created_at) : null,
+    };
+}
+function parseEmbed(e) {
+    // Rich-embed extras (fields/footer/timestamp) ride a JSON column that
+    // some payloads deliver pre-parsed and others as a string.
+    let rich = e?.raw_data ?? null;
+    if (typeof rich === 'string') {
+        try {
+            rich = JSON.parse(rich);
+        }
+        catch {
+            rich = null;
+        }
+    }
+    return {
+        id: String(e?.id ?? ''),
+        type: e?.type ?? 'link',
+        url: e?.url ?? null,
+        title: e?.title ?? null,
+        description: e?.description ?? null,
+        color: e?.color ?? null,
+        thumbnail: e?.thumbnail ?? null,
+        authorName: e?.author_name ?? null,
+        authorUrl: e?.author_url ?? null,
+        icon: e?.icon ?? null,
+        siteName: e?.site_name ?? null,
+        provider: e?.provider ?? null,
+        videoUrl: e?.video_url ?? null,
+        width: e?.width != null ? Number(e.width) : null,
+        height: e?.height != null ? Number(e.height) : null,
+        fields: Array.isArray(rich?.fields)
+            ? rich.fields.map((f) => ({
+                name: String(f?.name ?? ''),
+                value: String(f?.value ?? ''),
+                inline: f?.inline === true,
+            }))
+            : [],
+        footer: rich?.footer?.text != null ? { text: String(rich.footer.text) } : null,
+        timestamp: rich?.timestamp ?? null,
+        createdAt: e?.created_at ? new Date(e.created_at) : null,
+    };
+}
+/** A received message. */
+class Message {
+    constructor(client, data) {
+        this.client = client;
+        this.raw = data;
+        this.id = String(data.id);
+        this.channelId = String(data.channel_id);
+        this.serverId = data.server_id != null ? String(data.server_id) : null;
+        this.content = data.content ?? '';
+        const a = data.author ?? {};
+        this.author = parseAuthor({ ...a, id: a.id ?? data.author_id });
+        this.createdAt = data.created_at ? new Date(data.created_at) : null;
+        this.editedAt = data.updated_at ? new Date(data.updated_at) : null;
+        this.mentions = Array.isArray(data.mentions)
+            ? data.mentions.map((u) => ({ id: String(u?.id ?? u?.user_id ?? ''), username: u?.username ?? null }))
+            : [];
+        this.mentionRoleIds = Array.isArray(data.mention_role_ids) ? data.mention_role_ids.map(String) : [];
+        this.mentionEveryone = !!data.mention_everyone;
+        this.attachments = Array.isArray(data.attachments) ? data.attachments.map(parseAttachment) : [];
+        this.embeds = Array.isArray(data.embeds) ? data.embeds.map(parseEmbed) : [];
+        this.pinned = data.pinned === true;
+        const ref = data.reference;
+        if (ref && typeof ref === 'object' && ref.message_id != null) {
+            const reference = {
+                type: ref.type,
+                messageId: String(ref.message_id),
+                channelId: ref.channel_id != null ? String(ref.channel_id) : null,
+                serverId: ref.server_id != null ? String(ref.server_id) : null,
+            };
+            if ('message' in ref) {
+                const m = ref.message;
+                reference.message = m
+                    ? {
+                        id: String(m.id ?? reference.messageId),
+                        content: m.content ?? '',
+                        author: m.author ? parseAuthor(m.author) : null,
+                        createdAt: m.created_at ? new Date(m.created_at) : null,
+                        attachments: Array.isArray(m.attachments) ? m.attachments.map(parseAttachment) : [],
+                        embeds: Array.isArray(m.embeds) ? m.embeds.map(parseEmbed) : [],
+                    }
+                    : null;
+            }
+            this.reference = reference;
+        }
+        else {
+            this.reference = null;
+        }
+        const t = data.thread;
+        this.thread =
+            t && typeof t === 'object'
+                ? {
+                    id: t.id != null ? String(t.id) : null,
+                    replyCount: Number(t.reply_count || 0),
+                    lastActivityAt: t.last_activity_at ? new Date(t.last_activity_at) : null,
+                    deletedAt: t.deleted_at ? new Date(t.deleted_at) : null,
+                }
+                : null;
+    }
+    /**
+     * Compat alias (discord.js-style): the id of the message this one replies
+     * to, or `null`. Derived from {@link reference} — prefer that for new code;
+     * forwards and pins are not surfaced here.
+     */
+    get replyToId() {
+        return this.reference?.type === 'reply' ? this.reference.messageId : null;
+    }
+    /**
+     * The channel this message was sent in. Resolved from the SDK's name
+     * cache when available (`.name` populated); falls back to a minimal
+     * handle (`.name === null`) that still supports `.send()` while the
+     * cache lazily fills in the background.
+     */
+    get channel() {
+        return this.client.channels.get(this.channelId) ?? new Channel_1.Channel(this.client, { id: this.channelId, server_id: this.serverId });
+    }
+    /** The server this message was sent in, or `null` in a DM. Resolved from the SDK's cache. */
+    get server() {
+        return this.serverId ? this.client.servers.get(this.serverId) ?? null : null;
+    }
+    /** Reply to this message (threads it via `reply_to`). */
+    reply(content) {
+        const data = typeof content === 'string' ? { content } : content;
+        return this.client.rest.sendMessage(this.channelId, { ...data, replyTo: this.id });
+    }
+    /** Delete this message (needs MANAGE_MESSAGES, or it's the bot's own). */
+    delete() {
+        return this.client.deleteMessage(this.id);
+    }
+    /** React to this message. */
+    react(emoji) {
+        return this.client.react(this.id, emoji);
+    }
+    /** Remove the bot's own reaction from this message. */
+    removeReaction(emoji) {
+        return this.client.removeReaction(this.id, emoji);
+    }
+    /** Edit this message's content. Own messages only (403 otherwise). */
+    edit(content) {
+        return this.client.editMessage(this.id, content);
+    }
+    /** Pin this message. */
+    pin() {
+        return this.client.pinMessage(this.id);
+    }
+    /** Unpin this message. */
+    unpin() {
+        return this.client.unpinMessage(this.id);
+    }
+    /** The author as a server member (with `addRole`/`removeRole`), or null in DMs. */
+    get member() {
+        if (!this.serverId)
+            return null;
+        return new Member_1.Member(this.client, {
+            user_id: this.author.id,
+            username: this.author.username,
+            display_name: this.author.displayName,
+            avatar_url: this.author.avatarUrl,
+            is_bot: this.author.bot,
+            server_id: this.serverId,
+        });
+    }
+}
+exports.Message = Message;

package/dist/structures/Role.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A server role. Populated from `GET /servers/:serverId/roles` — see
+ * `Client#fetchRoles`/`Server#fetchRoles`. `permissions` is the raw decimal
+ * string bitmask as returned by the backend; parse it with `BigInt(...)` and
+ * test bits yourself (symbolic permission decoding isn't part of the SDK yet).
+ */
+export declare class Role {
+    readonly id: string;
+    readonly name: string;
+    readonly color: string | null;
+    /** Decimal string bitmask — parse with `BigInt(role.permissions)` if you need to test bits. */
+    readonly permissions: string;
+    readonly position: number;
+    /** The raw wire/REST payload, for anything the typed surface doesn't expose yet. */
+    readonly raw: any;
+    constructor(data: any);
+}

package/dist/structures/Role.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Role = void 0;
+/**
+ * A server role. Populated from `GET /servers/:serverId/roles` — see
+ * `Client#fetchRoles`/`Server#fetchRoles`. `permissions` is the raw decimal
+ * string bitmask as returned by the backend; parse it with `BigInt(...)` and
+ * test bits yourself (symbolic permission decoding isn't part of the SDK yet).
+ */
+class Role {
+    constructor(data) {
+        this.raw = data;
+        this.id = String(data.id ?? '');
+        this.name = data.name ?? '';
+        this.color = data.color ?? null;
+        this.permissions = data.permissions != null ? String(data.permissions) : '0';
+        this.position = typeof data.position === 'number' ? data.position : Number(data.position ?? 0);
+    }
+}
+exports.Role = Role;

package/dist/structures/Server.d.ts

@@ -0,0 +1,29 @@
+import type { Client } from '../Client';
+import type { Member } from './Member';
+import type { Role } from './Role';
+import type { FetchMembersOptions } from '../rest';
+import { ServerChannels } from './ServerChannels';
+/**
+ * A server (guild) the bot belongs to. Populated from `GET /servers` on
+ * connect and kept fresh by `server-meta-updated`/`server-deleted` events
+ * (requires `Intents.Servers`) — see `Client`'s server/channel name cache.
+ */
+export declare class Server {
+    private readonly client;
+    readonly id: string;
+    readonly name: string | null;
+    readonly iconUrl: string | null;
+    readonly ownerId: string | null;
+    /** The raw server row, for anything the typed surface doesn't expose yet. */
+    readonly raw: any;
+    constructor(client: Client, data: any);
+    /** List this server's members. */
+    fetchMembers(opts?: FetchMembersOptions): Promise<Member[]>;
+    /** List this server's roles. */
+    fetchRoles(): Promise<Role[]>;
+    /**
+     * This server's channels, from the SDK's cache (see {@link ServerChannels}
+     * — reflects cached state, not an authoritative fetch).
+     */
+    get channels(): ServerChannels;
+}

package/dist/structures/Server.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Server = void 0;
+const ServerChannels_1 = require("./ServerChannels");
+/**
+ * A server (guild) the bot belongs to. Populated from `GET /servers` on
+ * connect and kept fresh by `server-meta-updated`/`server-deleted` events
+ * (requires `Intents.Servers`) — see `Client`'s server/channel name cache.
+ */
+class Server {
+    constructor(client, data) {
+        this.client = client;
+        this.raw = data;
+        this.id = String(data.id ?? data._id ?? '');
+        this.name = data.name ?? null;
+        this.iconUrl = data.icon_url ?? data.iconUrl ?? null;
+        this.ownerId =
+            data.owner_id != null ? String(data.owner_id) : data.ownerId != null ? String(data.ownerId) : null;
+    }
+    /** List this server's members. */
+    fetchMembers(opts) {
+        return this.client.fetchMembers(this.id, opts);
+    }
+    /** List this server's roles. */
+    fetchRoles() {
+        return this.client.fetchRoles(this.id);
+    }
+    /**
+     * This server's channels, from the SDK's cache (see {@link ServerChannels}
+     * — reflects cached state, not an authoritative fetch).
+     */
+    get channels() {
+        return new ServerChannels_1.ServerChannels(this.client, this.id);
+    }
+}
+exports.Server = Server;

package/dist/structures/ServerChannels.d.ts

@@ -0,0 +1,24 @@
+import type { Client } from '../Client';
+import type { Channel } from './Channel';
+/**
+ * A lightweight, read-only view over the SDK's channel name cache
+ * (`Client#channels`), scoped to a single server. Backed entirely by
+ * whatever's currently cached — hydrated on connect and kept fresh via
+ * `channel-created`/`channel-updated`/`channel-deleted` events (see
+ * `Client#hydrateChannels`/`ensureChannel`) — **not** an authoritative,
+ * always-up-to-date fetch. A brand-new channel may be briefly absent until
+ * the cache catches up.
+ */
+export declare class ServerChannels {
+    private readonly client;
+    private readonly serverId;
+    constructor(client: Client, serverId: string);
+    /** Look up a cached channel by id, scoped to this server. */
+    get(id: string): Channel | undefined;
+    /** Find the first cached channel in this server with the given name. */
+    find(name: string): Channel | undefined;
+    /** All cached channels belonging to this server. */
+    all(): Channel[];
+    /** Count of cached channels belonging to this server. */
+    get size(): number;
+}

package/dist/structures/ServerChannels.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerChannels = void 0;
+/**
+ * A lightweight, read-only view over the SDK's channel name cache
+ * (`Client#channels`), scoped to a single server. Backed entirely by
+ * whatever's currently cached — hydrated on connect and kept fresh via
+ * `channel-created`/`channel-updated`/`channel-deleted` events (see
+ * `Client#hydrateChannels`/`ensureChannel`) — **not** an authoritative,
+ * always-up-to-date fetch. A brand-new channel may be briefly absent until
+ * the cache catches up.
+ */
+class ServerChannels {
+    constructor(client, serverId) {
+        this.client = client;
+        this.serverId = serverId;
+    }
+    /** Look up a cached channel by id, scoped to this server. */
+    get(id) {
+        const channel = this.client.channels.get(id);
+        return channel && channel.serverId === this.serverId ? channel : undefined;
+    }
+    /** Find the first cached channel in this server with the given name. */
+    find(name) {
+        for (const channel of this.client.channels.values()) {
+            if (channel.serverId === this.serverId && channel.name === name)
+                return channel;
+        }
+        return undefined;
+    }
+    /** All cached channels belonging to this server. */
+    all() {
+        const result = [];
+        for (const channel of this.client.channels.values()) {
+            if (channel.serverId === this.serverId)
+                result.push(channel);
+        }
+        return result;
+    }
+    /** Count of cached channels belonging to this server. */
+    get size() {
+        let count = 0;
+        for (const channel of this.client.channels.values()) {
+            if (channel.serverId === this.serverId)
+                count += 1;
+        }
+        return count;
+    }
+}
+exports.ServerChannels = ServerChannels;

package/dist/types.d.ts

@@ -0,0 +1,195 @@
+import type { Intent } from './intents';
+import type { Message } from './structures/Message';
+import type { Member } from './structures/Member';
+import type { Channel } from './structures/Channel';
+import type { Role } from './structures/Role';
+import type { PrivageConnectionError } from './errors';
+import type { Interaction } from './structures/Interaction';
+export interface ClientOptions {
+    /** Which event categories to receive. Declare only what you handle. */
+    intents: Intent[];
+    /** REST base. Defaults to `$PRIVAGE_API` or production (`https://api.privage.xyz`). Set for self-hosted/local dev. */
+    api?: string;
+    /** WebSocket base. Defaults to `$PRIVAGE_WS`, or production (`wss://ws.privage.xyz/socket`); with a custom `api` it's derived from it. */
+    ws?: string;
+    /** Emit raw wire frames and lifecycle detail on the `debug` event. */
+    debug?: boolean;
+}
+export interface BotUser {
+    id: string;
+    username: string;
+}
+export interface ReadyPayload {
+    user: BotUser;
+}
+export interface Author {
+    id: string;
+    username: string;
+    displayName: string | null;
+    avatarUrl: string | null;
+    /** True when this author is a bot — use it to guard against replying to yourself/other bots. */
+    bot: boolean;
+}
+export interface MessageDelete {
+    id: string;
+    channelId: string;
+    serverId: string | null;
+}
+export interface MessageDeleteBulk {
+    ids: string[];
+    channelId: string;
+    serverId: string | null;
+}
+export interface ReactionUpdate {
+    messageId: string;
+    channelId: string | null;
+    /** Current reaction summary for the message. */
+    reactions: unknown[];
+}
+/** A single reaction add/remove — who reacted with which emoji. */
+export interface ReactionAction {
+    messageId: string;
+    channelId: string | null;
+    emoji: string;
+    userId: string;
+}
+export interface MemberLeave {
+    userId: string;
+    serverId: string | null;
+}
+/** A role added to / removed from a member. */
+export interface RoleChange {
+    serverId: string;
+    userId: string;
+    roleId: string;
+}
+/**
+ * A partial member profile update. The wire `member-updated` and
+ * `nickname-updated` events each carry a different subset of fields — every
+ * field beyond `serverId`/`userId` is optional; read only what you need.
+ */
+export interface MemberUpdate {
+    serverId: string;
+    userId: string;
+    displayName?: string;
+    avatarUrl?: string;
+    nickname?: string;
+}
+/** A member was banned or unbanned. */
+export interface MemberBan {
+    serverId: string;
+    userId: string;
+    username: string;
+    displayName: string;
+}
+/** A member was timed out. */
+export interface MemberTimeout {
+    serverId: string;
+    userId: string;
+    until: Date | null;
+    moderatorId: string | null;
+    reason: string | null;
+}
+/** A member's timeout was lifted. */
+export interface MemberUntimeout {
+    serverId: string;
+    userId: string;
+}
+/** A message was pinned or unpinned. */
+export interface MessagePin {
+    messageId: string;
+    channelId: string;
+}
+/** A typing indicator started or stopped. */
+export interface TypingEvent {
+    userId: string;
+    channelId: string;
+}
+/** A channel was deleted. */
+export interface ChannelDelete {
+    channelId: string;
+    serverId: string | null;
+}
+/** A role was deleted. */
+export interface RoleDelete {
+    roleId: string;
+    serverId: string | null;
+}
+/** A member voted in a poll. */
+export interface PollVote {
+    pollId: string;
+    messageId: string;
+    voterId: string;
+    optionIdx: number;
+    totalVotes: number;
+}
+/** A poll closed. */
+export interface PollClose {
+    pollId: string;
+    messageId: string;
+    totalVotes: number;
+}
+/** Typed event map for `client.on(...)`. */
+export interface ClientEvents {
+    /** Fired once, after the first successful connect. */
+    ready: [ReadyPayload];
+    messageCreate: [Message];
+    messageUpdate: [Message];
+    messageDelete: [MessageDelete];
+    messageDeleteBulk: [MessageDeleteBulk];
+    reactionUpdate: [ReactionUpdate];
+    /** A specific user added a reaction (granular; needs the backend reaction delta). */
+    reactionAdd: [ReactionAction];
+    /** A specific user removed a reaction. */
+    reactionRemove: [ReactionAction];
+    memberJoin: [Member];
+    memberLeave: [MemberLeave];
+    /** A role was added to a member. */
+    roleAdd: [RoleChange];
+    /** A role was removed from a member. */
+    roleRemove: [RoleChange];
+    /** A member's profile changed (display name, avatar, and/or nickname — partial). */
+    memberUpdate: [MemberUpdate];
+    /** A member was banned. */
+    memberBan: [MemberBan];
+    /** A member's ban was lifted. */
+    memberUnban: [MemberBan];
+    /** A member was timed out. */
+    memberTimeout: [MemberTimeout];
+    /** A member's timeout was lifted. */
+    memberUntimeout: [MemberUntimeout];
+    /** A message was pinned. */
+    messagePin: [MessagePin];
+    /** A message was unpinned. */
+    messageUnpin: [MessagePin];
+    /** A user started typing in a channel. */
+    typingStart: [TypingEvent];
+    /** A user stopped typing in a channel. */
+    typingStop: [TypingEvent];
+    /** A channel was created. */
+    channelCreate: [Channel];
+    /** A channel was updated. */
+    channelUpdate: [Channel];
+    /** A channel was deleted. */
+    channelDelete: [ChannelDelete];
+    /** A role was created. */
+    roleCreate: [Role];
+    /** A role was updated. */
+    roleUpdate: [Role];
+    /** A role was deleted. */
+    roleDelete: [RoleDelete];
+    /** A member voted in a poll. */
+    pollVote: [PollVote];
+    /** A poll closed. */
+    pollClose: [PollClose];
+    /**
+     * A user interacted with the bot — button click, select-menu choice,
+     * slash-command invocation, or modal submission. Discriminate with
+     * `interaction.kind` (`'button' | 'select' | 'command' | 'modal_submit'`).
+     */
+    interaction: [Interaction];
+    /** Recoverable transport failure — the client is reconnecting. */
+    connectionError: [PrivageConnectionError];
+    warn: [string];
+    debug: [string];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "privage.js",
+  "version": "0.21.0",
+  "description": "Official SDK for building Privage bots.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "privage",
+    "bot",
+    "sdk",
+    "gateway",
+    "chat"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/privage-io/privage-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/privage-io/privage-sdk/issues"
+  },
+  "homepage": "https://github.com/privage-io/privage-sdk#readme",
+  "author": "Privage",
+  "license": "MIT",
+  "dependencies": {
+    "phoenix": "^1.7.14",
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "@types/phoenix": "^1.6.5",
+    "@types/ws": "^8.5.10",
+    "dotenv": "^17.4.2",
+    "typescript": "^5.4.5",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}