@bridgecord/sdk 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,263 @@
+interface BridgecordOptions {
+    /** The embed ID from your Bridgecord dashboard. */
+    embedId: string;
+    /** Optional session token for pre-authenticated users. */
+    sessionToken?: string;
+    /**
+     * Guest display name. When provided, the SDK will automatically authenticate
+     * as a guest with this name, skipping the welcome/auth screen.
+     */
+    displayName?: string;
+    /** Base URL of the Bridgecord API. Defaults to https://api.bridgecord.io */
+    apiUrl?: string;
+    /** Base URL of the Bridgecord embed app. Defaults to https://embed.bridgecord.io */
+    embedUrl?: string;
+}
+interface ConnectOptions {
+    /** The embed ID from your Bridgecord dashboard. */
+    embedId: string;
+    /** Optional session token for pre-authenticated users. */
+    sessionToken?: string;
+    /**
+     * Guest display name. When provided, the SDK will automatically authenticate
+     * as a guest with this name, skipping the welcome/auth screen.
+     */
+    displayName?: string;
+    /** Base URL of the Bridgecord API. Defaults to https://api.bridgecord.io */
+    apiUrl?: string;
+}
+interface BridgecordAuthor {
+    id: string;
+    username: string;
+    avatar: string | null;
+    roles: BridgecordRole[];
+}
+interface BridgecordRole {
+    id: string;
+    name: string;
+    color: number;
+    position: number;
+}
+interface BridgecordMessage {
+    id: string;
+    channelId: string;
+    serverId: string;
+    author: BridgecordAuthor;
+    content: string;
+    timestamp: string;
+    attachments: BridgecordAttachment[];
+    embeds: BridgecordEmbed[];
+}
+interface BridgecordAttachment {
+    id: string;
+    filename: string;
+    url: string;
+    contentType: string | null;
+    size: number;
+}
+interface BridgecordEmbed {
+    title?: string;
+    description?: string;
+    url?: string;
+    color?: number;
+    thumbnail?: {
+        url: string;
+        width?: number;
+        height?: number;
+    };
+    image?: {
+        url: string;
+        width?: number;
+        height?: number;
+    };
+    author?: {
+        name: string;
+        url?: string;
+        iconUrl?: string;
+    };
+    fields?: {
+        name: string;
+        value: string;
+        inline?: boolean;
+    }[];
+}
+interface BridgecordUser {
+    id: string;
+    type: "discord" | "guest";
+    displayName: string;
+    avatarUrl: string | null;
+    discordUserId?: string;
+}
+interface BridgecordChannel {
+    id: string;
+    name: string;
+    position: number;
+    locked: boolean;
+    pricingTier?: {
+        id: string;
+        name: string;
+        priceMonthly: number;
+    } | null;
+}
+interface BridgecordRewardProfile {
+    userId: string;
+    points: number;
+    level: number;
+    totalMessages: number;
+    currentStreak: number;
+    longestStreak: number;
+    badges: {
+        id: string;
+        name: string;
+        description: string;
+        iconUrl: string | null;
+        earnedAt: string;
+    }[];
+    rank: number;
+}
+interface BridgecordLeaderboardEntry {
+    userId: string;
+    displayName: string;
+    avatarUrl: string | null;
+    points: number;
+    level: number;
+    rank: number;
+}
+interface BridgecordEmbedConfig {
+    id: string;
+    serverId: string;
+    name: string;
+    authMode: "PUBLIC" | "DISCORD_OAUTH" | "API_AUTH" | "VIEW_ONLY";
+    enabled: boolean;
+    channels: BridgecordChannel[];
+    theme: BridgecordTheme | null;
+}
+interface BridgecordTheme {
+    primary: string;
+    background: string;
+    surface: string;
+    text: string;
+    textSecondary: string;
+    font: string;
+}
+interface BridgecordEventMap {
+    message: BridgecordMessage;
+    "messages:initial": BridgecordMessage[];
+    auth: BridgecordUser;
+    reward: BridgecordRewardEvent;
+    ready: undefined;
+    error: Error;
+    "channel:changed": BridgecordChannel;
+}
+interface BridgecordRewardEvent {
+    pointsEarned: number;
+    newTotal: number;
+    levelUp: boolean;
+    newLevel: number;
+    badgesEarned: {
+        id: string;
+        name: string;
+        description: string;
+        iconUrl: string | null;
+    }[];
+    streakUpdated: boolean;
+    currentStreak: number;
+}
+interface BridgecordConnection {
+    /** Current embed configuration. */
+    config: BridgecordEmbedConfig;
+    /** Currently connected channel ID. */
+    currentChannel: string | null;
+    /** Join a channel to receive messages. */
+    joinChannel(channelId: string): void;
+    /** Leave the current channel. */
+    leaveChannel(): void;
+    /** Send a message to the current channel. */
+    sendMessage(content: string): Promise<BridgecordMessage>;
+    /** Subscribe to events. */
+    on<K extends keyof BridgecordEventMap>(event: K, handler: (data: BridgecordEventMap[K]) => void): void;
+    /** Unsubscribe from events. */
+    off<K extends keyof BridgecordEventMap>(event: K, handler: (data: BridgecordEventMap[K]) => void): void;
+    /** Fetch user's reward profile. */
+    fetchRewards(): Promise<BridgecordRewardProfile>;
+    /** Fetch leaderboard. */
+    fetchLeaderboard(limit?: number, offset?: number): Promise<{
+        entries: BridgecordLeaderboardEntry[];
+        total: number;
+    }>;
+    /** Disconnect and clean up. */
+    destroy(): void;
+}
+
+/**
+ * Framework-agnostic Bridgecord SDK.
+ *
+ * @example
+ * ```ts
+ * const bc = new Bridgecord({ embedId: 'abc123' });
+ * bc.mount(document.getElementById('chat'));
+ * bc.on('message', (msg) => console.log(msg));
+ * // later...
+ * bc.destroy();
+ * ```
+ */
+declare class Bridgecord {
+    private readonly embedId;
+    private sessionToken?;
+    private readonly displayName?;
+    private readonly apiUrl;
+    private readonly embedUrl;
+    private iframe;
+    private container;
+    private listeners;
+    private messageHandler;
+    constructor(options: BridgecordOptions);
+    /**
+     * Authenticate as a guest with the configured displayName.
+     * Called automatically by mount() if displayName is set and no sessionToken exists.
+     * Returns the session token.
+     */
+    authenticateGuest(displayName?: string): Promise<string>;
+    /**
+     * Mount the Bridgecord embed into a container element.
+     * Creates an iframe pointing to the embed app.
+     *
+     * If `displayName` was provided in the constructor and no `sessionToken` exists,
+     * the SDK will first authenticate as a guest, then mount the iframe with the session.
+     */
+    mount(container: HTMLElement, options?: {
+        height?: number;
+        className?: string;
+    }): Promise<void>;
+    /**
+     * Subscribe to Bridgecord events.
+     */
+    on<K extends keyof BridgecordEventMap>(event: K, handler: (data: BridgecordEventMap[K]) => void): void;
+    /**
+     * Unsubscribe from Bridgecord events.
+     */
+    off<K extends keyof BridgecordEventMap>(event: K, handler: (data: BridgecordEventMap[K]) => void): void;
+    /**
+     * Destroy the embed and clean up all resources.
+     */
+    destroy(): void;
+    /**
+     * Open a direct Socket.io connection (no iframe).
+     * For developers who want complete rendering control.
+     */
+    static connect(options: ConnectOptions): Promise<BridgecordConnection>;
+    private buildIframeUrl;
+    private buildIframeUrlWithView;
+    /**
+     * Mount a single-channel chat view.
+     */
+    mountChat(container: HTMLElement, options?: {
+        channelId?: string;
+        height?: number;
+        className?: string;
+    }): void;
+    private handleIframeMessage;
+    private emit;
+}
+
+export { Bridgecord, type BridgecordAttachment, type BridgecordAuthor, type BridgecordChannel, type BridgecordConnection, type BridgecordEmbed, type BridgecordEmbedConfig, type BridgecordEventMap, type BridgecordLeaderboardEntry, type BridgecordMessage, type BridgecordOptions, type BridgecordRewardEvent, type BridgecordRewardProfile, type BridgecordRole, type BridgecordTheme, type BridgecordUser, type ConnectOptions };

package/dist/index.d.ts

@@ -0,0 +1,263 @@
+interface BridgecordOptions {
+    /** The embed ID from your Bridgecord dashboard. */
+    embedId: string;
+    /** Optional session token for pre-authenticated users. */
+    sessionToken?: string;
+    /**
+     * Guest display name. When provided, the SDK will automatically authenticate
+     * as a guest with this name, skipping the welcome/auth screen.
+     */
+    displayName?: string;
+    /** Base URL of the Bridgecord API. Defaults to https://api.bridgecord.io */
+    apiUrl?: string;
+    /** Base URL of the Bridgecord embed app. Defaults to https://embed.bridgecord.io */
+    embedUrl?: string;
+}
+interface ConnectOptions {
+    /** The embed ID from your Bridgecord dashboard. */
+    embedId: string;
+    /** Optional session token for pre-authenticated users. */
+    sessionToken?: string;
+    /**
+     * Guest display name. When provided, the SDK will automatically authenticate
+     * as a guest with this name, skipping the welcome/auth screen.
+     */
+    displayName?: string;
+    /** Base URL of the Bridgecord API. Defaults to https://api.bridgecord.io */
+    apiUrl?: string;
+}
+interface BridgecordAuthor {
+    id: string;
+    username: string;
+    avatar: string | null;
+    roles: BridgecordRole[];
+}
+interface BridgecordRole {
+    id: string;
+    name: string;
+    color: number;
+    position: number;
+}
+interface BridgecordMessage {
+    id: string;
+    channelId: string;
+    serverId: string;
+    author: BridgecordAuthor;
+    content: string;
+    timestamp: string;
+    attachments: BridgecordAttachment[];
+    embeds: BridgecordEmbed[];
+}
+interface BridgecordAttachment {
+    id: string;
+    filename: string;
+    url: string;
+    contentType: string | null;
+    size: number;
+}
+interface BridgecordEmbed {
+    title?: string;
+    description?: string;
+    url?: string;
+    color?: number;
+    thumbnail?: {
+        url: string;
+        width?: number;
+        height?: number;
+    };
+    image?: {
+        url: string;
+        width?: number;
+        height?: number;
+    };
+    author?: {
+        name: string;
+        url?: string;
+        iconUrl?: string;
+    };
+    fields?: {
+        name: string;
+        value: string;
+        inline?: boolean;
+    }[];
+}
+interface BridgecordUser {
+    id: string;
+    type: "discord" | "guest";
+    displayName: string;
+    avatarUrl: string | null;
+    discordUserId?: string;
+}
+interface BridgecordChannel {
+    id: string;
+    name: string;
+    position: number;
+    locked: boolean;
+    pricingTier?: {
+        id: string;
+        name: string;
+        priceMonthly: number;
+    } | null;
+}
+interface BridgecordRewardProfile {
+    userId: string;
+    points: number;
+    level: number;
+    totalMessages: number;
+    currentStreak: number;
+    longestStreak: number;
+    badges: {
+        id: string;
+        name: string;
+        description: string;
+        iconUrl: string | null;
+        earnedAt: string;
+    }[];
+    rank: number;
+}
+interface BridgecordLeaderboardEntry {
+    userId: string;
+    displayName: string;
+    avatarUrl: string | null;
+    points: number;
+    level: number;
+    rank: number;
+}
+interface BridgecordEmbedConfig {
+    id: string;
+    serverId: string;
+    name: string;
+    authMode: "PUBLIC" | "DISCORD_OAUTH" | "API_AUTH" | "VIEW_ONLY";
+    enabled: boolean;
+    channels: BridgecordChannel[];
+    theme: BridgecordTheme | null;
+}
+interface BridgecordTheme {
+    primary: string;
+    background: string;
+    surface: string;
+    text: string;
+    textSecondary: string;
+    font: string;
+}
+interface BridgecordEventMap {
+    message: BridgecordMessage;
+    "messages:initial": BridgecordMessage[];
+    auth: BridgecordUser;
+    reward: BridgecordRewardEvent;
+    ready: undefined;
+    error: Error;
+    "channel:changed": BridgecordChannel;
+}
+interface BridgecordRewardEvent {
+    pointsEarned: number;
+    newTotal: number;
+    levelUp: boolean;
+    newLevel: number;
+    badgesEarned: {
+        id: string;
+        name: string;
+        description: string;
+        iconUrl: string | null;
+    }[];
+    streakUpdated: boolean;
+    currentStreak: number;
+}
+interface BridgecordConnection {
+    /** Current embed configuration. */
+    config: BridgecordEmbedConfig;
+    /** Currently connected channel ID. */
+    currentChannel: string | null;
+    /** Join a channel to receive messages. */
+    joinChannel(channelId: string): void;
+    /** Leave the current channel. */
+    leaveChannel(): void;
+    /** Send a message to the current channel. */
+    sendMessage(content: string): Promise<BridgecordMessage>;
+    /** Subscribe to events. */
+    on<K extends keyof BridgecordEventMap>(event: K, handler: (data: BridgecordEventMap[K]) => void): void;
+    /** Unsubscribe from events. */
+    off<K extends keyof BridgecordEventMap>(event: K, handler: (data: BridgecordEventMap[K]) => void): void;
+    /** Fetch user's reward profile. */
+    fetchRewards(): Promise<BridgecordRewardProfile>;
+    /** Fetch leaderboard. */
+    fetchLeaderboard(limit?: number, offset?: number): Promise<{
+        entries: BridgecordLeaderboardEntry[];
+        total: number;
+    }>;
+    /** Disconnect and clean up. */
+    destroy(): void;
+}
+
+/**
+ * Framework-agnostic Bridgecord SDK.
+ *
+ * @example
+ * ```ts
+ * const bc = new Bridgecord({ embedId: 'abc123' });
+ * bc.mount(document.getElementById('chat'));
+ * bc.on('message', (msg) => console.log(msg));
+ * // later...
+ * bc.destroy();
+ * ```
+ */
+declare class Bridgecord {
+    private readonly embedId;
+    private sessionToken?;
+    private readonly displayName?;
+    private readonly apiUrl;
+    private readonly embedUrl;
+    private iframe;
+    private container;
+    private listeners;
+    private messageHandler;
+    constructor(options: BridgecordOptions);
+    /**
+     * Authenticate as a guest with the configured displayName.
+     * Called automatically by mount() if displayName is set and no sessionToken exists.
+     * Returns the session token.
+     */
+    authenticateGuest(displayName?: string): Promise<string>;
+    /**
+     * Mount the Bridgecord embed into a container element.
+     * Creates an iframe pointing to the embed app.
+     *
+     * If `displayName` was provided in the constructor and no `sessionToken` exists,
+     * the SDK will first authenticate as a guest, then mount the iframe with the session.
+     */
+    mount(container: HTMLElement, options?: {
+        height?: number;
+        className?: string;
+    }): Promise<void>;
+    /**
+     * Subscribe to Bridgecord events.
+     */
+    on<K extends keyof BridgecordEventMap>(event: K, handler: (data: BridgecordEventMap[K]) => void): void;
+    /**
+     * Unsubscribe from Bridgecord events.
+     */
+    off<K extends keyof BridgecordEventMap>(event: K, handler: (data: BridgecordEventMap[K]) => void): void;
+    /**
+     * Destroy the embed and clean up all resources.
+     */
+    destroy(): void;
+    /**
+     * Open a direct Socket.io connection (no iframe).
+     * For developers who want complete rendering control.
+     */
+    static connect(options: ConnectOptions): Promise<BridgecordConnection>;
+    private buildIframeUrl;
+    private buildIframeUrlWithView;
+    /**
+     * Mount a single-channel chat view.
+     */
+    mountChat(container: HTMLElement, options?: {
+        channelId?: string;
+        height?: number;
+        className?: string;
+    }): void;
+    private handleIframeMessage;
+    private emit;
+}
+
+export { Bridgecord, type BridgecordAttachment, type BridgecordAuthor, type BridgecordChannel, type BridgecordConnection, type BridgecordEmbed, type BridgecordEmbedConfig, type BridgecordEventMap, type BridgecordLeaderboardEntry, type BridgecordMessage, type BridgecordOptions, type BridgecordRewardEvent, type BridgecordRewardProfile, type BridgecordRole, type BridgecordTheme, type BridgecordUser, type ConnectOptions };