@wireblob/wire 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdulbasit Rubeya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,293 @@
+# Wireblobs JavaScript SDK (Wire JS)
+
+A lightweight realtime SDK for connecting to the Wireblob realtime network using a Pusher-compatible protocol.
+
+Wire is built as a wrapper around `pusher-js`, providing:
+
+- simpler configuration
+- Wireblob-first defaults
+- browser support
+- Node.js support
+- React Native compatibility
+- Web Worker compatibility
+- future extensibility without breaking API compatibility
+
+## Installation
+
+### NPM
+
+```bash
+npm install @wireblob/wire
+```
+
+### Yarn
+
+```bash
+yarn add @wireblob/wire
+```
+
+### PNPM
+
+```bash
+pnpm add @wireblob/wire
+```
+
+## Quick Start
+
+### Browser / Bundlers
+
+```js
+import Wire from '@wireblob/wire';
+
+const wire = new Wire('YOUR_APP_KEY', {
+  host: 'eu-central-1.wireblob.com',
+  secure: true
+});
+
+const channel = wire.subscribe('chat');
+
+channel.bind('message', (data) => {
+  console.log(data);
+});
+```
+
+### CDN Usage
+
+The CDN file is a self-contained browser bundle. You do not need to load `pusher-js` separately.
+
+```html
+<script src="https://cdn.wireblob.com/wire/latest/wire.min.js"></script>
+
+<script>
+  const wire = new Wire('YOUR_APP_KEY', {
+    host: 'eu-central-1.wireblob.com',
+    secure: true
+  });
+
+  const channel = wire.subscribe('chat');
+
+  channel.bind('message', (data) => {
+    console.log(data);
+  });
+</script>
+```
+
+
+## Constructor
+
+```js
+new Wire(appKey, options)
+```
+
+### Parameters
+
+| Parameter | Type     | Required | Description            |
+| --------- | -------- | -------- | ---------------------- |
+| `appKey`  | `string` | Yes      | Application public key |
+| `options` | `object` | No       | Connection options     |
+
+
+## Configuration Options
+
+| Option              | Type      | Default         | Description                     |
+| ------------------- | --------- | --------------- | ------------------------------- |
+| `host`              | `string`  | `eu-central-1.wireblob.com` | Wireblob server hostname |
+| `secure`            | `boolean` | `true`          | Use secure websocket connection |
+| `wsPort`            | `number`  | `80`            | WebSocket port                  |
+| `wssPort`           | `number`  | `443`           | Secure WebSocket port           |
+| `enabledTransports` | `array`   | `['ws', 'wss']` | Allowed transports              |
+| `authEndpoint`      | `string`  | `null`          | Private/presence auth endpoint  |
+| `auth`              | `object`  | `{}`            | Additional auth configuration   |
+
+
+## Subscribing to Channels
+
+```js
+const channel = wire.subscribe('chat-room');
+```
+
+## Listening for Events
+
+```js
+channel.bind('message', (data) => {
+  console.log(data);
+});
+```
+
+## Triggering Events
+
+Client-triggered events require private or presence channels.
+
+```js
+channel.trigger('client-message', {
+  text: 'Hello world'
+});
+```
+
+## Unsubscribing
+
+```js
+wire.unsubscribe('chat-room');
+```
+
+## Connection Events
+
+### Connected
+
+```js
+wire.connection.bind('connected', () => {
+  console.log('Connected');
+});
+```
+
+### Error
+
+```js
+wire.connection.bind('error', (error) => {
+  console.error(error);
+});
+```
+
+### Disconnected
+
+```js
+wire.connection.bind('disconnected', () => {
+  console.log('Disconnected');
+});
+```
+
+### Manual Connect / Disconnect
+
+```js
+wire.connect();
+wire.disconnect();
+```
+
+
+## Private Channels
+
+```js
+const channel = wire.subscribe('private-chat');
+```
+
+### Server Auth Endpoint (Laravel example)
+
+```php
+Route::post('/broadcasting/auth', function () {
+    return Broadcast::auth(request());
+});
+```
+
+## Presence Channels
+
+```js
+const channel = wire.subscribe('presence-room');
+
+channel.bind('pusher:subscription_succeeded', (members) => {
+  console.log(members);
+});
+```
+
+
+## Node.js Usage
+
+Install websocket support:
+
+```bash
+npm install ws
+```
+
+```js
+import Wire from '@wireblob/wire';
+import WebSocket from 'ws';
+
+global.WebSocket = WebSocket;
+
+const wire = new Wire('YOUR_APP_KEY', {
+  host: 'eu-central-1.wireblob.com',
+  secure: true
+});
+```
+
+## React Native
+
+Wire works in React Native environments supporting WebSocket.
+
+```js
+import Wire from '@wireblob/wire';
+```
+
+## Web Workers
+
+```js
+import Wire from '@wireblob/wire/worker';
+
+const wire = new Wire('YOUR_APP_KEY', {
+  host: 'eu-central-1.wireblob.com'
+});
+```
+
+
+## Advanced Configuration
+
+```js
+const wire = new Wire('YOUR_APP_KEY', {
+  host: 'eu-central-1.wireblob.com',
+  secure: true,
+  wsPort: 80,
+  wssPort: 443,
+  enabledTransports: ['ws', 'wss'],
+  authEndpoint: '/broadcasting/auth',
+  auth: {
+    headers: {
+      Authorization: 'Bearer TOKEN'
+    }
+  }
+});
+```
+
+
+## Debugging
+
+Enable internal Pusher logging:
+
+```js
+Wire.logToConsole = true;
+```
+
+
+## Architecture
+
+Wire is:
+
+- protocol-compatible with Pusher Channels
+- transport-compatible with standard WebSocket infrastructure
+- designed for Wireblob-native extensions
+
+Current implementation:
+
+- wraps `pusher-js`
+- applies Wireblob defaults
+- exposes a stable SDK surface
+
+Future versions may introduce:
+
+- native Wire transport
+- SSE support
+- QUIC/WebTransport
+- MQTT adapters
+- custom protocol optimizations
+
+
+## Compatibility
+
+| Platform     | Supported |
+| ------------ | --------- |
+| Browser      | Yes       |
+| Node.js      | Yes       |
+| React Native | Yes       |
+| Web Workers  | Yes       |
+
+
+## Credits
+- [Pusher](https://pusher.com) - Protocol and transport compatibility

package/lib/commonjs/wire.js

@@ -0,0 +1,53 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _pusherJs = _interopRequireDefault(require("pusher-js"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const DEFAULT_HOST = 'eu-central-1.wireblob.com';
+class Wire {
+  constructor(appKey, options = {}) {
+    if (!appKey || typeof appKey !== 'string') {
+      throw new TypeError('Wire requires a valid appKey string.');
+    }
+    const secure = options.secure ?? true;
+    const host = options.host ?? DEFAULT_HOST;
+    const pusherOptions = {
+      wsHost: host,
+      forceTLS: secure,
+      wsPort: options.wsPort ?? 80,
+      wssPort: options.wssPort ?? 443,
+      enabledTransports: options.enabledTransports ?? ['ws', 'wss'],
+      cluster: ''
+    };
+    if (options.authEndpoint) {
+      pusherOptions.authEndpoint = options.authEndpoint;
+    }
+    if (options.auth) {
+      pusherOptions.auth = options.auth;
+    }
+    this.pusher = new _pusherJs.default(appKey, pusherOptions);
+    this.connection = this.pusher.connection;
+  }
+  subscribe(channelName) {
+    return this.pusher.subscribe(channelName);
+  }
+  unsubscribe(channelName) {
+    this.pusher.unsubscribe(channelName);
+  }
+  connect() {
+    this.pusher.connect();
+  }
+  disconnect() {
+    this.pusher.disconnect();
+  }
+  static get logToConsole() {
+    return _pusherJs.default.logToConsole;
+  }
+  static set logToConsole(value) {
+    _pusherJs.default.logToConsole = Boolean(value);
+  }
+}
+var _default = exports.default = Wire;

package/lib/commonjs/worker.js

@@ -0,0 +1,9 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _wire = _interopRequireDefault(require("./wire"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _default = exports.default = _wire.default;

package/lib/es/wire.js

@@ -0,0 +1,48 @@
+import Pusher from 'pusher-js';
+const DEFAULT_HOST = 'eu-central-1.wireblob.com';
+class Wire {
+  constructor(appKey) {
+    var _options$secure, _options$host, _options$wsPort, _options$wssPort, _options$enabledTrans;
+    let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    if (!appKey || typeof appKey !== 'string') {
+      throw new TypeError('Wire requires a valid appKey string.');
+    }
+    const secure = (_options$secure = options.secure) !== null && _options$secure !== void 0 ? _options$secure : true;
+    const host = (_options$host = options.host) !== null && _options$host !== void 0 ? _options$host : DEFAULT_HOST;
+    const pusherOptions = {
+      wsHost: host,
+      forceTLS: secure,
+      wsPort: (_options$wsPort = options.wsPort) !== null && _options$wsPort !== void 0 ? _options$wsPort : 80,
+      wssPort: (_options$wssPort = options.wssPort) !== null && _options$wssPort !== void 0 ? _options$wssPort : 443,
+      enabledTransports: (_options$enabledTrans = options.enabledTransports) !== null && _options$enabledTrans !== void 0 ? _options$enabledTrans : ['ws', 'wss'],
+      cluster: ''
+    };
+    if (options.authEndpoint) {
+      pusherOptions.authEndpoint = options.authEndpoint;
+    }
+    if (options.auth) {
+      pusherOptions.auth = options.auth;
+    }
+    this.pusher = new Pusher(appKey, pusherOptions);
+    this.connection = this.pusher.connection;
+  }
+  subscribe(channelName) {
+    return this.pusher.subscribe(channelName);
+  }
+  unsubscribe(channelName) {
+    this.pusher.unsubscribe(channelName);
+  }
+  connect() {
+    this.pusher.connect();
+  }
+  disconnect() {
+    this.pusher.disconnect();
+  }
+  static get logToConsole() {
+    return Pusher.logToConsole;
+  }
+  static set logToConsole(value) {
+    Pusher.logToConsole = Boolean(value);
+  }
+}
+export default Wire;

package/lib/es/worker.js

@@ -0,0 +1,2 @@
+import Wire from './wire';
+export default Wire;