@nice2dev/game-engine 1.1.5 → 1.1.6

package/dist/types/systems/NiceSocial.d.ts

@@ -0,0 +1,580 @@
+/**
+ * NiceSocial - Social & Friends System
+ *
+ * Comprehensive social system for managing friends, parties, guilds,
+ * chat, presence, and social interactions.
+ *
+ * Features:
+ * - Friend list management
+ * - Friend requests (send/accept/decline)
+ * - Block list
+ * - Online presence
+ * - Activity status
+ * - Party/group system
+ * - Guild/clan support
+ * - Social feed
+ * - Chat integration
+ * - Social leaderboards
+ * - Social achievements
+ * - Cross-platform support
+ * - Privacy settings
+ *
+ * @packageDocumentation
+ */
+import { EventEmitter } from 'events';
+/** Unique user ID */
+export type UserId = string;
+/** Unique party ID */
+export type PartyId = string;
+/** Unique guild ID */
+export type GuildId = string;
+/** Unique message ID */
+export type MessageId = string;
+/** Unique activity ID */
+export type ActivityId = string;
+/** Unique invite ID */
+export type InviteId = string;
+/** Online status */
+export type OnlineStatus = 'online' | 'away' | 'busy' | 'offline' | 'invisible';
+/** Friend request status */
+export type FriendRequestStatus = 'pending' | 'accepted' | 'declined' | 'cancelled';
+/** Relationship type */
+export type RelationshipType = 'friend' | 'blocked' | 'pending_incoming' | 'pending_outgoing' | 'none';
+/** Activity type */
+export type ActivityType = 'playing' | 'in_lobby' | 'in_match' | 'in_menu' | 'spectating' | 'away' | 'custom';
+/** Party role */
+export type PartyRole = 'leader' | 'member';
+/** Guild role */
+export type GuildRole = 'owner' | 'admin' | 'officer' | 'member';
+/** Message type */
+export type MessageType = 'text' | 'image' | 'system' | 'invite' | 'achievement';
+/** Privacy level */
+export type PrivacyLevel = 'public' | 'friends' | 'private';
+/** User profile */
+export interface UserProfile {
+    id: UserId;
+    username: string;
+    displayName: string;
+    avatar?: string;
+    banner?: string;
+    bio?: string;
+    level: number;
+    title?: string;
+    badges: string[];
+    isVerified: boolean;
+    isPremium: boolean;
+    createdAt: number;
+    lastOnline: number;
+}
+/** User presence */
+export interface UserPresence {
+    userId: UserId;
+    status: OnlineStatus;
+    activity?: UserActivity;
+    lastStatusChange: number;
+    platform?: string;
+    gameVersion?: string;
+}
+/** User activity */
+export interface UserActivity {
+    type: ActivityType;
+    title: string;
+    details?: string;
+    imageKey?: string;
+    partyId?: PartyId;
+    partySize?: number;
+    partyMax?: number;
+    startTime: number;
+    endTime?: number;
+    canJoin?: boolean;
+    canSpectate?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Friend data */
+export interface Friend {
+    userId: UserId;
+    profile: UserProfile;
+    presence: UserPresence;
+    nickname?: string;
+    favorited: boolean;
+    addedAt: number;
+    lastInteraction?: number;
+    mutualFriends: number;
+    notes?: string;
+}
+/** Friend request */
+export interface FriendRequest {
+    id: string;
+    fromUserId: UserId;
+    toUserId: UserId;
+    message?: string;
+    status: FriendRequestStatus;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Blocked user */
+export interface BlockedUser {
+    userId: UserId;
+    username: string;
+    reason?: string;
+    blockedAt: number;
+}
+/** Party info */
+export interface SocialParty {
+    id: PartyId;
+    name?: string;
+    leaderId: UserId;
+    members: PartyMember[];
+    maxSize: number;
+    isPublic: boolean;
+    inviteCode?: string;
+    createdAt: number;
+    activity?: string;
+    settings: PartySettings;
+}
+/** Party member */
+export interface PartyMember {
+    userId: UserId;
+    role: PartyRole;
+    joinedAt: number;
+    isReady: boolean;
+    profile: UserProfile;
+    presence: UserPresence;
+}
+/** Party settings */
+export interface PartySettings {
+    joinability: 'open' | 'invite_only' | 'friends_only';
+    allowInvites: boolean;
+    autoAcceptFriends: boolean;
+    voiceChatEnabled: boolean;
+}
+/** Party invite */
+export interface PartyInvite {
+    id: InviteId;
+    partyId: PartyId;
+    fromUserId: UserId;
+    toUserId: UserId;
+    partyName?: string;
+    message?: string;
+    expiresAt: number;
+    createdAt: number;
+}
+/** Guild info */
+export interface Guild {
+    id: GuildId;
+    name: string;
+    tag: string;
+    description?: string;
+    icon?: string;
+    banner?: string;
+    ownerId: UserId;
+    memberCount: number;
+    maxMembers: number;
+    level: number;
+    xp: number;
+    createdAt: number;
+    isRecruiting: boolean;
+    requirements?: GuildRequirements;
+    settings: GuildSettings;
+}
+/** Guild member */
+export interface GuildMember {
+    userId: UserId;
+    role: GuildRole;
+    joinedAt: number;
+    contribution: number;
+    lastActive: number;
+    profile: UserProfile;
+    note?: string;
+}
+/** Guild requirements */
+export interface GuildRequirements {
+    minLevel?: number;
+    minPlaytime?: number;
+    applicationRequired: boolean;
+}
+/** Guild settings */
+export interface GuildSettings {
+    privacy: PrivacyLevel;
+    allowApplications: boolean;
+    requireApproval: boolean;
+    defaultRole: GuildRole;
+}
+/** Chat message */
+export interface ChatMessage {
+    id: MessageId;
+    channelId: string;
+    senderId: UserId;
+    senderName: string;
+    type: MessageType;
+    content: string;
+    attachments?: string[];
+    replyTo?: MessageId;
+    reactions?: Record<string, UserId[]>;
+    isEdited: boolean;
+    isDeleted: boolean;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+/** Social feed item */
+export interface SocialFeedItem {
+    id: ActivityId;
+    type: 'achievement' | 'level_up' | 'friend_added' | 'guild_joined' | 'custom';
+    userId: UserId;
+    userProfile: UserProfile;
+    title: string;
+    description?: string;
+    image?: string;
+    timestamp: number;
+    likes: number;
+    comments: number;
+    isLiked: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Privacy settings */
+export interface SocialPrivacySettings {
+    profileVisibility: PrivacyLevel;
+    activityVisibility: PrivacyLevel;
+    friendListVisibility: PrivacyLevel;
+    allowFriendRequests: boolean;
+    allowPartyInvites: boolean;
+    allowGuildInvites: boolean;
+    allowDirectMessages: 'everyone' | 'friends' | 'none';
+    showOnlineStatus: boolean;
+    showActivity: boolean;
+}
+/** Social statistics */
+export interface SocialStatistics {
+    totalFriends: number;
+    totalBlocked: number;
+    requestsSent: number;
+    requestsReceived: number;
+    partiesJoined: number;
+    guildsJoined: number;
+    messagesSent: number;
+    activitiesGenerated: number;
+}
+/** Social event types */
+export type SocialEventType = 'friend_added' | 'friend_removed' | 'friend_request_received' | 'friend_request_sent' | 'friend_request_accepted' | 'friend_request_declined' | 'user_blocked' | 'user_unblocked' | 'presence_updated' | 'activity_updated' | 'party_created' | 'party_joined' | 'party_left' | 'party_disbanded' | 'party_invite_received' | 'party_member_joined' | 'party_member_left' | 'party_leader_changed' | 'guild_joined' | 'guild_left' | 'guild_invite_received' | 'guild_member_joined' | 'guild_member_left' | 'guild_role_changed' | 'message_received' | 'message_sent' | 'feed_item_added' | 'privacy_updated';
+/** Social event data */
+export interface SocialEvent {
+    type: SocialEventType;
+    timestamp: number;
+    userId?: UserId;
+    targetUserId?: UserId;
+    partyId?: PartyId;
+    guildId?: GuildId;
+    messageId?: MessageId;
+    data?: unknown;
+}
+/** Social event callback */
+export type SocialEventCallback = (event: SocialEvent) => void;
+/** Social system configuration */
+export interface SocialConfig {
+    maxFriends: number;
+    maxBlocked: number;
+    maxPendingRequests: number;
+    maxPartySize: number;
+    maxGuildSize: number;
+    friendRequestExpireDays: number;
+    partyInviteExpireMinutes: number;
+    activityFeedSize: number;
+    presenceUpdateIntervalMs: number;
+    enableRichPresence: boolean;
+    enableActivityFeed: boolean;
+    enableGuilds: boolean;
+    autoDeclineDuplicateRequests: boolean;
+}
+/** Default configuration */
+export declare const DEFAULT_SOCIAL_CONFIG: SocialConfig;
+/**
+ * Social and friends system
+ */
+export declare class NiceSocial extends EventEmitter {
+    private config;
+    private currentUser?;
+    private currentPresence;
+    private friends;
+    private blocked;
+    private incomingRequests;
+    private outgoingRequests;
+    private currentParty?;
+    private partyInvites;
+    private currentGuild?;
+    private guildMembers;
+    private activityFeed;
+    private privacySettings;
+    private statistics;
+    private presenceInterval?;
+    constructor(config?: Partial<SocialConfig>);
+    /**
+     * Emit social event
+     */
+    private emitEvent;
+    /**
+     * Generate unique ID
+     */
+    private generateId;
+    /**
+     * Initialize with current user
+     */
+    initialize(profile: UserProfile): void;
+    /**
+     * Get current user profile
+     */
+    getCurrentUser(): UserProfile | undefined;
+    /**
+     * Update current user profile
+     */
+    updateProfile(updates: Partial<UserProfile>): void;
+    /**
+     * Start presence update interval
+     */
+    private startPresenceUpdates;
+    /**
+     * Broadcast current presence
+     */
+    private broadcastPresence;
+    /**
+     * Set online status
+     */
+    setStatus(status: OnlineStatus): void;
+    /**
+     * Get current status
+     */
+    getStatus(): OnlineStatus;
+    /**
+     * Set activity
+     */
+    setActivity(activity: UserActivity): void;
+    /**
+     * Clear activity
+     */
+    clearActivity(): void;
+    /**
+     * Get current presence
+     */
+    getPresence(): UserPresence;
+    /**
+     * Get friend presence
+     */
+    getFriendPresence(userId: UserId): UserPresence | undefined;
+    /**
+     * Update friend presence (from server)
+     */
+    updateFriendPresence(userId: UserId, presence: UserPresence): void;
+    /**
+     * Send friend request
+     */
+    sendFriendRequest(toUserId: UserId, message?: string): boolean;
+    /**
+     * Receive friend request (from server)
+     */
+    receiveFriendRequest(request: FriendRequest): void;
+    /**
+     * Accept friend request
+     */
+    acceptFriendRequest(requestId: string): boolean;
+    /**
+     * Decline friend request
+     */
+    declineFriendRequest(requestId: string): boolean;
+    /**
+     * Cancel outgoing friend request
+     */
+    cancelFriendRequest(requestId: string): boolean;
+    /**
+     * Remove friend
+     */
+    removeFriend(userId: UserId): boolean;
+    /**
+     * Set friend nickname
+     */
+    setFriendNickname(userId: UserId, nickname: string | undefined): boolean;
+    /**
+     * Toggle friend favorite
+     */
+    toggleFriendFavorite(userId: UserId): boolean;
+    /**
+     * Set friend notes
+     */
+    setFriendNotes(userId: UserId, notes: string | undefined): boolean;
+    /**
+     * Get friend
+     */
+    getFriend(userId: UserId): Friend | undefined;
+    /**
+     * Get all friends
+     */
+    getAllFriends(): Friend[];
+    /**
+     * Get online friends
+     */
+    getOnlineFriends(): Friend[];
+    /**
+     * Get favorite friends
+     */
+    getFavoriteFriends(): Friend[];
+    /**
+     * Get friends in game
+     */
+    getFriendsInGame(): Friend[];
+    /**
+     * Search friends
+     */
+    searchFriends(query: string): Friend[];
+    /**
+     * Get incoming friend requests
+     */
+    getIncomingRequests(): FriendRequest[];
+    /**
+     * Get outgoing friend requests
+     */
+    getOutgoingRequests(): FriendRequest[];
+    /**
+     * Check relationship type
+     */
+    getRelationship(userId: UserId): RelationshipType;
+    /**
+     * Block user
+     */
+    blockUser(userId: UserId, reason?: string): boolean;
+    /**
+     * Unblock user
+     */
+    unblockUser(userId: UserId): boolean;
+    /**
+     * Check if user is blocked
+     */
+    isBlocked(userId: UserId): boolean;
+    /**
+     * Get blocked users
+     */
+    getBlockedUsers(): BlockedUser[];
+    /**
+     * Create party
+     */
+    createParty(settings?: Partial<PartySettings>): SocialParty;
+    /**
+     * Invite to party
+     */
+    inviteToParty(userId: UserId, message?: string): PartyInvite | undefined;
+    /**
+     * Receive party invite
+     */
+    receivePartyInvite(invite: PartyInvite): void;
+    /**
+     * Accept party invite
+     */
+    acceptPartyInvite(inviteId: InviteId): boolean;
+    /**
+     * Decline party invite
+     */
+    declinePartyInvite(inviteId: InviteId): boolean;
+    /**
+     * Join party (from server response)
+     */
+    joinParty(party: SocialParty): void;
+    /**
+     * Leave party
+     */
+    leaveParty(): boolean;
+    /**
+     * Kick party member (leader only)
+     */
+    kickPartyMember(userId: UserId): boolean;
+    /**
+     * Transfer party leadership
+     */
+    transferPartyLeadership(userId: UserId): boolean;
+    /**
+     * Set party member ready state
+     */
+    setReady(ready: boolean): boolean;
+    /**
+     * Get current party
+     */
+    getCurrentParty(): SocialParty | undefined;
+    /**
+     * Get party invites
+     */
+    getPartyInvites(): PartyInvite[];
+    /**
+     * Check if all party members are ready
+     */
+    isPartyReady(): boolean;
+    /**
+     * Join guild
+     */
+    joinGuild(guild: Guild): void;
+    /**
+     * Leave guild
+     */
+    leaveGuild(): boolean;
+    /**
+     * Get current guild
+     */
+    getCurrentGuild(): Guild | undefined;
+    /**
+     * Get guild members
+     */
+    getGuildMembers(): GuildMember[];
+    /**
+     * Update guild member (from server)
+     */
+    updateGuildMember(member: GuildMember): void;
+    /**
+     * Add feed item
+     */
+    addFeedItem(item: SocialFeedItem): void;
+    /**
+     * Get activity feed
+     */
+    getActivityFeed(limit?: number): SocialFeedItem[];
+    /**
+     * Like feed item
+     */
+    likeFeedItem(activityId: ActivityId): boolean;
+    /**
+     * Send message (would typically go through server)
+     */
+    sendMessage(channelId: string, content: string, replyTo?: MessageId): ChatMessage;
+    /**
+     * Receive message (from server)
+     */
+    receiveMessage(message: ChatMessage): void;
+    /**
+     * Get privacy settings
+     */
+    getPrivacySettings(): SocialPrivacySettings;
+    /**
+     * Update privacy settings
+     */
+    updatePrivacySettings(updates: Partial<SocialPrivacySettings>): void;
+    /**
+     * Get social statistics
+     */
+    getStatistics(): SocialStatistics;
+    /**
+     * Export social state
+     */
+    exportState(): object;
+    /**
+     * Import social state
+     */
+    importState(state: {
+        friends?: [UserId, Friend][];
+        blocked?: [UserId, BlockedUser][];
+        privacySettings?: SocialPrivacySettings;
+        statistics?: SocialStatistics;
+    }): void;
+    /**
+     * Destroy social system
+     */
+    destroy(): void;
+}
+/**
+ * Create social system instance
+ */
+export declare function createSocialSystem(config?: Partial<SocialConfig>): NiceSocial;
+export default NiceSocial;