@strapi-community/plugin-io 1.0.0

package/package.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json.schemastore.org/package",
+  "name": "@strapi-community/plugin-io",
+  "version": "1.0.0",
+  "description": "A plugin for Strapi CMS that provides the ability for Socket IO integration",
+  "keywords": [
+    "strapi",
+    "strapi-plugin",
+    "plugin",
+    "strapi plugin",
+    "socket",
+    "socket io",
+    "io"
+  ],
+  "type": "commonjs",
+  "exports": {
+    "./package.json": "./package.json",
+    "./strapi-admin": {
+      "source": "./admin/src/index.js",
+      "import": "./dist/admin/index.mjs",
+      "require": "./dist/admin/index.js",
+      "default": "./dist/admin/index.js"
+    },
+    "./strapi-server": {
+      "source": "./server/index.js",
+      "import": "./dist/server/index.mjs",
+      "require": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "types.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "strapi-plugin build",
+    "watch": "strapi-plugin watch",
+    "watch:link": "strapi-plugin watch:link",
+    "verify": "strapi-plugin verify",
+    "lint": "eslint . --fix",
+    "format": "prettier --write \"./**/*.{js,json,yml,md}\""
+  },
+  "dependencies": {
+    "date-fns": "^3.6.0",
+    "socket.io": "^4.8.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.2",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.1",
+    "@strapi/design-system": "^2.0.2",
+    "@strapi/icons": "^2.0.2",
+    "@strapi/sdk-plugin": "^5.3.2",
+    "@strapi/strapi": "^5.33.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.2",
+    "prettier": "^3.7.4",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.30.2",
+    "semantic-release": "^24.2.3",
+    "styled-components": "^6.1.19"
+  },
+  "peerDependencies": {
+    "@strapi/design-system": "^2.0.0-rc.1",
+    "@strapi/icons": "^2.0.0-rc.1",
+    "@strapi/strapi": "^5.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "react-router-dom": "^6.0.0",
+    "styled-components": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@strapi/design-system": {
+      "optional": true
+    },
+    "@strapi/icons": {
+      "optional": true
+    }
+  },
+  "strapi": {
+    "name": "io",
+    "displayName": "IO",
+    "description": "A plugin for Strapi CMS that provides the ability for Socket IO integration",
+    "kind": "plugin"
+  },
+  "engines": {
+    "node": ">=18.0.0 <=22.x.x",
+    "npm": ">=6.0.0"
+  },
+  "author": {
+    "name": "@ComfortablyCoding",
+    "url": "https://github.com/ComfortablyCoding"
+  },
+  "maintainers": [
+    {
+      "name": "@ComfortablyCoding",
+      "url": "https://github.com/ComfortablyCoding",
+      "lead": true
+    },
+    {
+      "name": "@hrdunn",
+      "url": "https://github.com/hrdunn"
+    }
+  ],
+  "homepage": "https://github.com/strapi-community/plugin-io#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/strapi-community/plugin-io.git"
+  },
+  "bugs": {
+    "url": "https://github.com/strapi-community/plugin-io/issues"
+  },
+  "license": "MIT"
+}

package/types.d.ts

@@ -0,0 +1,362 @@
+/// <reference types="node" />
+import { Server as SocketIOServer, Socket, Namespace } from 'socket.io';
+import type { Core } from '@strapi/strapi';
+
+declare module '@strapi/strapi' {
+  export interface Strapi {
+    /**
+     * Global Socket.IO instance with helper functions
+     * @example
+     * strapi.$io.server.emit('notification', data);
+     * strapi.$io.joinRoom(socketId, 'premium-users');
+     */
+    $io: SocketIO;
+    
+    /**
+     * Current plugin settings (read-only)
+     * @example
+     * const maxConnections = strapi.$ioSettings.connection.maxConnections;
+     */
+    $ioSettings?: PluginSettings;
+  }
+}
+
+export interface SocketIOConfig {
+  events?: SocketEvent[];
+  hooks?: {
+    init?: (context: { strapi: Core.Strapi; $io: SocketIO }) => void | Promise<void>;
+  };
+  contentTypes?: Array<string | ContentTypeConfig>;
+  socket?: {
+    serverOptions?: any;
+  };
+  /**
+   * Additional sensitive field names to exclude from emitted data.
+   * These are added to the default list which includes:
+   * password, resetPasswordToken, confirmationToken, refreshToken,
+   * accessToken, secret, apiKey, privateKey, token, salt, hash
+   * 
+   * @example
+   * sensitiveFields: ['creditCard', 'ssn', 'socialSecurityNumber']
+   */
+  sensitiveFields?: string[];
+}
+
+export interface SocketEvent {
+  name: string;
+  handler: (
+    context: { strapi: Core.Strapi; io: SocketIO },
+    socket: Socket,
+    ...args: any[]
+  ) => void | Promise<void>;
+}
+
+/**
+ * Populate configuration for content type events.
+ * Supports multiple formats for flexibility.
+ */
+export type PopulateConfig = 
+  | '*'                              // Populate all relations (1 level deep)
+  | true                             // Alias for '*'
+  | string[]                         // Specific relations: ['author', 'category']
+  | Record<string, any>;             // Strapi populate syntax: { author: { fields: ['name'] } }
+
+export interface ContentTypeConfig {
+  /** Content type UID (e.g., 'api::article.article') */
+  uid: string;
+  /** Actions to emit events for. Defaults to all: ['create', 'update', 'delete'] */
+  actions?: Array<'create' | 'update' | 'delete'>;
+  /**
+   * Populate relations when emitting events.
+   * When configured, the plugin will refetch the entity with populated relations
+   * after create/update operations before emitting the event.
+   * 
+   * @example
+   * // Populate all relations
+   * populate: '*'
+   * 
+   * @example
+   * // Populate specific relations
+   * populate: ['author', 'category']
+   * 
+   * @example
+   * // Strapi populate syntax with field selection
+   * populate: { 
+   *   author: { fields: ['username', 'email'] },
+   *   category: true 
+   * }
+   */
+  populate?: PopulateConfig;
+}
+
+export interface EmitOptions {
+  event: 'create' | 'update' | 'delete';
+  schema: any;
+  data: any;
+}
+
+export interface RawEmitOptions {
+  event: string;
+  data: any;
+  rooms?: string[];
+}
+
+export interface SocketIOMetrics {
+  totalEmits: number;
+  cachedLookups: number;
+  connectedSockets: number;
+  errors: number;
+  cacheSize: {
+    rooms: number;
+    abilities: number;
+  };
+}
+
+export class SocketIO {
+  constructor(options?: any);
+  
+  /**
+   * Emit a content type event with sanitization and permission checking
+   */
+  emit(options: EmitOptions): Promise<void>;
+  
+  /**
+   * Emit a raw event to specified rooms
+   */
+  raw(options: RawEmitOptions): Promise<void>;
+  
+  /**
+   * Invalidate the internal cache
+   */
+  invalidateCache(): void;
+  
+  /**
+   * Get current metrics
+   */
+  getMetrics(): SocketIOMetrics;
+  
+  /**
+   * Get the underlying Socket.IO server instance
+   */
+  readonly server: SocketIOServer;
+  
+  /**
+   * All configured namespaces
+   */
+  namespaces?: Record<string, Namespace>;
+  
+  /**
+   * Join socket to room
+   */
+  joinRoom?(socketId: string, roomName: string): boolean;
+  
+  /**
+   * Remove socket from room
+   */
+  leaveRoom?(socketId: string, roomName: string): boolean;
+  
+  /**
+   * Get all sockets in room
+   */
+  getSocketsInRoom?(roomName: string): Promise<Array<{ id: string; user: any }>>;
+  
+  /**
+   * Send private message to specific socket
+   */
+  sendPrivateMessage?(socketId: string, event: string, data: any): void;
+  
+  /**
+   * Broadcast from socket to all others
+   */
+  broadcast?(socketId: string, event: string, data: any): void;
+  
+  /**
+   * Emit to namespace
+   */
+  emitToNamespace?(namespace: string, event: string, data: any): void;
+  
+  /**
+   * Force disconnect socket
+   */
+  disconnectSocket?(socketId: string, reason?: string): boolean;
+  
+  /**
+   * Subscribe a socket to a specific entity (server-side)
+   */
+  subscribeToEntity?(socketId: string, uid: string, id: string | number): Promise<EntitySubscriptionResult>;
+  
+  /**
+   * Unsubscribe a socket from a specific entity
+   */
+  unsubscribeFromEntity?(socketId: string, uid: string, id: string | number): EntitySubscriptionResult;
+  
+  /**
+   * Get all entity subscriptions for a socket
+   */
+  getEntitySubscriptions?(socketId: string): EntitySubscriptionsResult;
+  
+  /**
+   * Emit an event to all clients subscribed to a specific entity
+   */
+  emitToEntity?(uid: string, id: string | number, event: string, data: any): void;
+  
+  /**
+   * Get all sockets subscribed to a specific entity
+   */
+  getEntityRoomSockets?(uid: string, id: string | number): Promise<Array<{ id: string; user: any }>>;
+  
+  /**
+   * Cleanup and destroy the Socket.IO instance
+   */
+  destroy(): Promise<void>;
+}
+
+export interface EntitySubscriptionResult {
+  success: boolean;
+  room?: string;
+  uid?: string;
+  id?: string | number;
+  error?: string;
+}
+
+export interface EntitySubscriptionsResult {
+  success: boolean;
+  subscriptions?: Array<{ uid: string; id: string; room: string }>;
+  error?: string;
+}
+
+/**
+ * Plugin Settings
+ */
+export interface PluginSettings {
+  enabled: boolean;
+  cors: { origins: string[] };
+  connection: {
+    maxConnections: number;
+    pingTimeout: number;
+    pingInterval: number;
+    connectionTimeout: number;
+  };
+  security: {
+    requireAuthentication: boolean;
+    rateLimiting: {
+      enabled: boolean;
+      maxEventsPerSecond: number;
+    };
+    ipWhitelist: string[];
+    ipBlacklist: string[];
+  };
+  events: {
+    customEventNames: boolean;
+    includeRelations: boolean;
+    excludeFields: string[];
+    onlyPublished: boolean;
+  };
+  rooms: {
+    autoJoinByRole: Record<string, string[]>;
+    enablePrivateRooms: boolean;
+  };
+  rolePermissions: Record<string, RolePermission>;
+  redis: {
+    enabled: boolean;
+    url: string;
+  };
+  namespaces: {
+    enabled: boolean;
+    list: Record<string, { requireAuth: boolean }>;
+  };
+  monitoring: {
+    enableConnectionLogging: boolean;
+    enableEventLogging: boolean;
+    maxEventLogSize: number;
+  };
+}
+
+export interface RolePermission {
+  canConnect: boolean;
+  allowCredentials: boolean;
+  allowedMethods: string[];
+  contentTypes: Record<string, {
+    create: boolean;
+    update: boolean;
+    delete: boolean;
+  }>;
+}
+
+/**
+ * Settings Service
+ */
+export interface SettingsService {
+  getSettings(): Promise<PluginSettings>;
+  setSettings(newSettings: Partial<PluginSettings>): Promise<PluginSettings>;
+  getDefaultSettings(): PluginSettings;
+}
+
+/**
+ * Monitoring Service
+ */
+export interface MonitoringService {
+  getConnectionStats(): ConnectionStats;
+  getEventStats(): EventStats;
+  getEventLog(limit?: number): EventLogEntry[];
+  logEvent(eventType: string, data?: any): void;
+  resetStats(): void;
+  sendTestEvent(eventName?: string, data?: any): TestEventResult;
+}
+
+export interface ConnectionStats {
+  connected: number;
+  rooms: Array<{ name: string; members: number; isEntityRoom?: boolean }>;
+  sockets: Array<{
+    id: string;
+    connected: boolean;
+    rooms: string[];
+    entitySubscriptions?: Array<{ uid: string; id: string; room: string }>;
+    handshake: {
+      address: string;
+      time: string;
+      query: Record<string, string>;
+    };
+    user: any;
+  }>;
+  entitySubscriptions?: {
+    total: number;
+    byContentType: Record<string, number>;
+    rooms: string[];
+  };
+}
+
+export interface EventStats {
+  totalEvents: number;
+  eventsByType: Record<string, number>;
+  lastReset: number;
+  eventsPerSecond: string | number;
+}
+
+export interface EventLogEntry {
+  timestamp: number;
+  type: string;
+  data: any;
+}
+
+export interface TestEventResult {
+  success: boolean;
+  eventName: string;
+  data: any;
+  recipients: number;
+}
+
+/**
+ * Extend Strapi plugin services
+ */
+declare module '@strapi/strapi' {
+  export interface PluginServices {
+    io?: {
+      settings: SettingsService;
+      monitoring: MonitoringService;
+    };
+  }
+}
+
+export default SocketIO;
+