@modernman00/shared-js-lib 1.2.89 → 1.6.2

package/README.md

@@ -129,6 +129,84 @@ mix.js('resources/js/app.js', 'public/js')
 
 
 
+### Example: AI Client Utilities (£0 Serverless AI)
+```javascript
+import { AiVoiceRecorder, AiMediaGuard, AiSemanticSearch } from '@modernman00/shared-js-lib';
+
+// 1. Voice-to-Text Recording (Whisper via Backend Proxy)
+const recorder = new AiVoiceRecorder({
+    uploadUrl: '/api/ai/transcribe',
+    onStateChange: (state) => console.log('Recording state:', state),
+    onError: (err) => alert(err.message)
+});
+
+await recorder.start();
+// ... later
+const blob = await recorder.stop();
+const { text } = await recorder.uploadAndTranscribe(blob);
+document.querySelector('#task-input').value = text;
+
+// 2. Photo NSFW Guard (Fail-Closed Image Safety Pre-check)
+const file = document.querySelector('input[type="file"]').files[0];
+const validation = AiMediaGuard.validateFile(file, { maxSizeBytes: 10 * 1024 * 1024 });
+if (!validation.valid) {
+    alert(validation.error);
+    return;
+}
+const safety = await AiMediaGuard.precheckPhotoSafety(file, '/api/ai/moderate-photo');
+if (safety.flagged) {
+    alert('Photo rejected: content contains NSFW imagery.');
+}
+
+// 3. Instant Semantic Search (Debounced & Abort-Protected)
+const searchController = new AiSemanticSearch({
+    searchUrl: '/api/ai/semantic-search',
+    minQueryLength: 3,
+    debounceMs: 350,
+    onResults: (results) => renderCards(results),
+    onLoading: (isLoading) => toggleSpinner(isLoading)
+});
+
+document.querySelector('#search-input').addEventListener('input', (e) => {
+    searchController.handleInput(e.target.value);
+});
+// 4. Generative Event Flyer Studio (AI Art + Razor-Sharp Canvas Typography)
+import { AiFlyerStudio, AiBillSplitter, AiEntertainmentPrompt } from '@modernman00/shared-js-lib';
+
+const studio = new AiFlyerStudio({ width: 800, height: 1200 });
+await studio.setBackgroundImage(aiGeneratedBackgroundDataUri);
+studio.setData({
+    title: 'Liam 7th Birthday',
+    subtitle: 'Jurassic Dinosaur Adventure',
+    date: 'Saturday, 12 Nov',
+    time: '3:00 PM',
+    location: 'St. James Hall',
+    hostName: 'Sarah & Mark'
+});
+studio.render();
+studio.download('liam-birthday-flyer.png');
+
+// 5. Multimodal Bill & Bar Tab Splitter (Camera Photo -> Itemized Guest Assignment)
+const splitter = new AiBillSplitter({ defaultTipPercent: 12.5 });
+const scanResult = await splitter.scanReceipt(receiptPhotoFile);
+if (scanResult.success) {
+    splitter.addGuest('g1', 'Alice');
+    splitter.addGuest('g2', 'Bob');
+    splitter.assignItem(0, 'g1'); // Alice pays for Nachos
+    splitter.assignItem(0, 'g2'); // Bob shares Nachos
+    const breakdown = splitter.calculateShares(10); // per-guest breakdown with tip
+}
+
+// 6. AI Speechwriter & Roast Master
+const speech = await AiEntertainmentPrompt.requestSpeech({
+    honoureeName: 'Dave',
+    occasion: '30th Birthday',
+    anecdotes: ['Fell into pool in Ibiza', 'Sourdough bread fanatic'],
+    tone: 'humorous_roast'
+});
+console.log(speech.speechText, speech.toast);
+```
+
 Updating the Package
 To update to the latest version, run:
 npm update @modernman00/shared-js-lib

package/SovereignBroadcasterClient.js

@@ -0,0 +1,325 @@
+/**
+ * SovereignBroadcasterClient
+ * 
+ * Engineered by the Advanced Technology Group (ATG) under Olutobi (Deloitte) and Victor (CTO).
+ * High-performance, zero-npm, drop-in replacement for Pusher JS.
+ * Connects directly to SovereignBroadcaster PHP SSE endpoints with auto-reconnect,
+ * HMAC channel authentication, and presence tracking.
+ */
+
+export class SovereignChannel {
+  constructor(name, broadcaster) {
+    this.name = name;
+    this.broadcaster = broadcaster;
+    this.callbacks = new Map();
+    this.members = new Map();
+    this.subscribed = false;
+  }
+
+  bind(event, callback) {
+    if (!this.callbacks.has(event)) {
+      this.callbacks.set(event, []);
+    }
+    this.callbacks.get(event).push(callback);
+    return this;
+  }
+
+  unbind(event, callback) {
+    if (!this.callbacks.has(event)) return this;
+    if (!callback) {
+      this.callbacks.delete(event);
+    } else {
+      const filtered = this.callbacks.get(event).filter(cb => cb !== callback);
+      this.callbacks.set(event, filtered);
+    }
+    return this;
+  }
+
+  emit(event, data) {
+    const cbs = this.callbacks.get(event);
+    if (cbs && cbs.length > 0) {
+      cbs.forEach(cb => {
+        try {
+          cb(data);
+        } catch (e) {
+          console.error(`[SovereignBroadcaster] Error in event listener for ${event}:`, e);
+        }
+      });
+    }
+  }
+}
+
+export class SovereignBroadcasterClient {
+  constructor(options = {}) {
+    this.endpoint = options.endpoint || '/api/broadcasting/events';
+    this.authEndpoint = options.authEndpoint || '/api/broadcasting/auth';
+    this.headers = options.headers || {};
+    this.channels = new Map();
+    this.socketId = this._generateSocketId();
+    this.lastEventId = 0;
+    this.reconnectAttempts = 0;
+    this.maxReconnectDelay = 15000;
+    this.isConnected = false;
+
+    if (typeof document !== 'undefined' && !this.headers['X-CSRF-TOKEN']) {
+      const metaCsrf = document.querySelector('meta[name="csrf-token"]');
+      if (metaCsrf && metaCsrf.content) {
+        this.headers['X-CSRF-TOKEN'] = metaCsrf.content;
+      }
+    }
+  }
+
+  _generateSocketId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+      const arr = new Uint32Array(2);
+      crypto.getRandomValues(arr);
+      return `${arr[0]}.${arr[1]}`;
+    }
+    const rand1 = Math.floor(Math.random() * 1000000);
+    const rand2 = Math.floor(Math.random() * 1000000);
+    return `${rand1}.${rand2}`;
+  }
+
+  subscribe(channelName) {
+    if (typeof channelName !== 'string' || !/^[A-Za-z0-9_.:@-]{1,191}$/.test(channelName)) {
+      throw new Error('[SovereignBroadcaster] Invalid channel identifier');
+    }
+    if (this.channels.has(channelName)) {
+      return this.channels.get(channelName);
+    }
+
+    const channel = new SovereignChannel(channelName, this);
+    this.channels.set(channelName, channel);
+
+    if (channelName.startsWith('private-') || channelName.startsWith('presence-')) {
+      this._authorizeChannel(channelName)
+        .then(authData => {
+          channel.authData = authData || {};
+          channel.subscribed = true;
+          this._connectSse(channelName);
+          channel.emit('pusher:subscription_succeeded', authData);
+        })
+        .catch(err => {
+          console.error(`[SovereignBroadcaster] Authorization failed for ${channelName}:`, err);
+          channel.emit('pusher:subscription_error', err);
+        });
+    } else {
+      channel.subscribed = true;
+      this._connectSse(channelName);
+      channel.emit('pusher:subscription_succeeded', {});
+    }
+
+    return channel;
+  }
+
+  unsubscribe(channelName) {
+    if (!this.channels.has(channelName)) return;
+    const channel = this.channels.get(channelName);
+    channel.subscribed = false;
+    this.channels.delete(channelName);
+
+    if (channel._eventSource) {
+      channel._eventSource.close();
+    }
+  }
+
+  _authorizeChannel(channelName) {
+    return fetch(this.authEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+        ...this.headers
+      },
+      body: JSON.stringify({
+        channel_name: channelName,
+        socket_id: this.socketId
+      })
+    }).then(res => {
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status} auth failure`);
+      }
+      return res.json();
+    });
+  }
+
+  _connectSse(channelName) {
+    const channel = this.channels.get(channelName);
+    if (!channel || typeof window === 'undefined' || typeof EventSource === 'undefined') return;
+
+    const origin = window.location ? window.location.origin : 'http://localhost';
+    const url = new URL(this.endpoint, origin);
+    url.searchParams.set('channel', channelName);
+    url.searchParams.set('socket_id', this.socketId);
+    if (channel.authData && channel.authData.auth) {
+      url.searchParams.set('auth', String(channel.authData.auth));
+    }
+    if (channel.authData && channel.authData.channel_data) {
+      url.searchParams.set('channel_data', String(channel.authData.channel_data));
+    }
+    if (this.lastEventId > 0) {
+      url.searchParams.set('last_event_id', String(this.lastEventId));
+    }
+
+    const es = new EventSource(url.toString());
+    channel._eventSource = es;
+
+    es.onopen = () => {
+      this.isConnected = true;
+      this.reconnectAttempts = 0;
+    };
+
+    es.onmessage = (e) => {
+      if (e.lastEventId) {
+        this.lastEventId = parseInt(e.lastEventId, 10);
+      }
+      try {
+        const parsed = JSON.parse(e.data);
+        const eventName = parsed.event || 'message';
+        const payload = parsed.data !== undefined ? parsed.data : parsed;
+        channel.emit(eventName, payload);
+      } catch (err) {
+        channel.emit('message', e.data);
+      }
+    };
+
+    es.onerror = () => {
+      this.isConnected = false;
+      es.close();
+
+      if (channel.subscribed) {
+        this.reconnectAttempts++;
+        const delay = Math.min(1000 * Math.pow(1.5, this.reconnectAttempts), this.maxReconnectDelay);
+        setTimeout(() => {
+          if (channel.subscribed) {
+            this._connectSse(channelName);
+          }
+        }, delay);
+      }
+    };
+  }
+
+  disconnect() {
+    this.channels.forEach(ch => {
+      ch.subscribed = false;
+      if (ch._eventSource) {
+        ch._eventSource.close();
+      }
+    });
+    this.channels.clear();
+    this.isConnected = false;
+  }
+}
+
+/**
+ * HybridBroadcasterClient
+ * 
+ * Provides primary Pusher routing with automatic, zero-downtime failover to
+ * SovereignBroadcaster if Pusher fails, disconnects, times out, or throws an error.
+ */
+export class HybridBroadcasterClient {
+  constructor(options = {}) {
+    this.pusherKey = options.pusherKey || options.key || '';
+    this.pusherOptions = options.pusherOptions || { cluster: options.cluster || 'eu' };
+    this.sovereignOptions = {
+      endpoint: options.endpoint || '/api/broadcasting/events',
+      authEndpoint: options.authEndpoint || '/api/broadcasting/auth',
+      headers: options.headers || {}
+    };
+    this.activeClient = null;
+    this.channels = new Map();
+    this.isUsingFallback = false;
+    this.connectTimeoutMs = options.connectTimeoutMs || 4000;
+
+    this._initTransport();
+  }
+
+  _initTransport() {
+    const hasPusher = typeof window !== 'undefined' && typeof window.Pusher === 'function' && this.pusherKey !== '';
+    if (hasPusher) {
+      try {
+        const pusherInstance = new window.Pusher(this.pusherKey, this.pusherOptions);
+        this.activeClient = pusherInstance;
+
+        if (pusherInstance.connection) {
+          pusherInstance.connection.bind('error', (err) => {
+            console.warn('[HybridBroadcaster] Pusher error encountered, failing over to SovereignBroadcaster:', err);
+            this._failoverToSovereign();
+          });
+          pusherInstance.connection.bind('unavailable', () => {
+            console.warn('[HybridBroadcaster] Pusher unavailable, failing over to SovereignBroadcaster');
+            this._failoverToSovereign();
+          });
+          pusherInstance.connection.bind('failed', () => {
+            console.warn('[HybridBroadcaster] Pusher connection failed, failing over to SovereignBroadcaster');
+            this._failoverToSovereign();
+          });
+
+          setTimeout(() => {
+            if (pusherInstance.connection.state !== 'connected' && !this.isUsingFallback) {
+              console.warn('[HybridBroadcaster] Pusher connection timeout exceeded, failing over to SovereignBroadcaster');
+              this._failoverToSovereign();
+            }
+          }, this.connectTimeoutMs);
+        }
+      } catch (e) {
+        console.warn('[HybridBroadcaster] Failed to initialise Pusher, defaulting to SovereignBroadcaster:', e);
+        this._failoverToSovereign();
+      }
+    } else {
+      this._failoverToSovereign();
+    }
+  }
+
+  _failoverToSovereign() {
+    if (this.isUsingFallback) return;
+    this.isUsingFallback = true;
+    const sovereign = new SovereignBroadcasterClient(this.sovereignOptions);
+    this.activeClient = sovereign;
+
+    this.channels.forEach((channelData, channelName) => {
+      const sovChannel = sovereign.subscribe(channelName);
+      channelData.events.forEach((callbacks, eventName) => {
+        callbacks.forEach(cb => sovChannel.bind(eventName, cb));
+      });
+    });
+  }
+
+  subscribe(channelName) {
+    if (!this.channels.has(channelName)) {
+      this.channels.set(channelName, { events: new Map() });
+    }
+
+    const channelProxy = {
+      name: channelName,
+      bind: (event, callback) => {
+        const chData = this.channels.get(channelName);
+        if (!chData.events.has(event)) {
+          chData.events.set(event, []);
+        }
+        chData.events.get(event).push(callback);
+
+        if (this.activeClient && typeof this.activeClient.subscribe === 'function') {
+          const sub = this.activeClient.subscribe(channelName);
+          if (sub && typeof sub.bind === 'function') {
+            sub.bind(event, callback);
+          }
+        }
+        return channelProxy;
+      }
+    };
+
+    if (this.activeClient && typeof this.activeClient.subscribe === 'function') {
+      this.activeClient.subscribe(channelName);
+    }
+
+    return channelProxy;
+  }
+
+  disconnect() {
+    if (this.activeClient && typeof this.activeClient.disconnect === 'function') {
+      this.activeClient.disconnect();
+    }
+    this.channels.clear();
+  }
+}