@sockethub/client 5.0.0-alpha.8 → 5.0.0-beta.0

package/README.md

@@ -1,77 +1,209 @@
 # @sockethub/client
 
-JavaScript client for [Sockethub](https://github.com/sockethub/sockethub) - a protocol
-gateway that translates ActivityStreams messages into various protocols (XMPP, IRC, RSS, etc.).
-
-Works in Node.js and browsers.
+The Sockethub client is a small JavaScript SDK for app developers to connect to a
+Sockethub server via Socket.IO and send/receive ActivityStreams messages. It works
+in both Node.js and browsers, with schema-driven validation, automatic
+reconnection, and credential replay.
+
+## What's Included
+
+- `SockethubClient` for connection and message handling
+- `SockethubClient.connect(baseUrl)` discovers the server's Socket.IO endpoint
+  from its service descriptor, so apps need only the base URL
+- Schema-driven validation of outbound ActivityStreams messages (via `@sockethub/schemas`)
+- `contextFor(platform)` builds canonical `@context` arrays from server metadata
+- `ready()` promise and `ready`/`init_error` observability events
+- Automatic outbound queuing until initialization is complete
+- Auto-replay of credentials and connections on reconnect
+- A browser-ready bundle in `dist/`
+
+## How It Works
+
+`SockethubClient` wraps a [Socket.IO](https://socket.io) connection and manages
+everything between your app and the Sockethub server:
+
+1. **Schema registry handshake.** On connect (and every reconnect) the client
+   requests the server's *platform schema registry* — the contexts, versions,
+   and JSON schemas for each platform the server has loaded. It caches that
+   registry along with a content fingerprint the server provides. On reconnect
+   the client echoes the fingerprint; if nothing has changed the server replies
+   `unchanged` instead of re-sending the full schema set, so the (potentially
+   large) registry crosses the wire only when it actually changes.
+2. **Initialization lifecycle.** `ready()` resolves once the registry is
+   applied; `getInitState()` and the `ready` / `init_error` events expose the
+   same lifecycle. Outbound events emitted before the client is ready are queued
+   in memory and flushed automatically once initialization completes.
+3. **Message handling.** Outgoing `message`/`credentials` events are normalized
+   (string `actor`/`target` references are expanded to objects) and validated
+   against the originating platform's schema before they leave the client;
+   incoming platform events are normalized before being handed to your
+   `message` listener. Validation uses the same schemas the server enforces, so
+   malformed activities are caught locally rather than round-tripping.
+4. **Context composition.** `contextFor(platform)` builds the canonical
+   `@context` array for a platform from the cached registry.
+5. **Reconnect resilience.** Credentials, platform connections, and room joins
+   are kept in memory and replayed when the socket reconnects (see
+   [Security & State Management](#security--state-management)).
 
 ## Install
 
 ### Node.js
 
-`$ npm install @sockethub/client`
+`$ npm install @sockethub/client socket.io-client`
 
 ### Bun
 
-`$ bun install @sockethub/client`
-
-#### CommonJS
-
-```javascript
-const SockethubClient = require('@sockethub/client');
-const io = require('@socket.io-client');
-const SOCKETHUB_SERVER = 'http://localhost:10550';
-const sc = SockethubClient(io(SOCKETHUB_SERVER));
-```
-
-#### ESM
+`$ bun install @sockethub/client socket.io-client`
 
 ```javascript
 import SockethubClient from '@sockethub/client';
-import { io } from '@socket.io-client';
-const SOCKETHUB_SERVER = 'http://localhost:10550';
-const sc = SockethubClient(io(SOCKETHUB_SERVER));
+const sc = await SockethubClient.connect('http://localhost:10550');
 ```
 
+`socket.io-client` is an optional peer dependency: `connect()` imports it when
+no `io` global is present, and the constructor accepts a socket you created
+yourself.
+
 ### Browser
 
-The browser bundle is available in the dist folder:
+Two browser builds are published in `dist/`:
 
-```
-import '@sockethub/client/dist/sockethub-client.js';
-```
+- `dist/sockethub-client.browser.js` is the IIFE/global build for plain `<script>` tags
+- `dist/sockethub-client.js` is the ESM build for `<script type="module">`
 
-You can place it somewhere accessible from the web and include
-it via a `script` tag.
+If you are serving assets from a Sockethub server, use the pre-copied global build
+at `/sockethub-client.js` along with `/socket.io.js`:
 
-```
-<script src="http://example.com/sockethub-client.js" type="module"></script>
+```html
+<script src="/socket.io.js"></script>
+<script src="/sockethub-client.js"></script>
 ```
 
-Once included in a web-page, the `SockethubClient` base object
-should be on the global scope.
+These scripts set `io` and `SockethubClient` as globals.
+
+If you are hosting the package files yourself and want ESM instead, serve
+`dist/sockethub-client.js` and import it from a module script:
+
+```html
+<script type="module">
+import SockethubClient from '/dist/sockethub-client.js';
+import { io } from '/socket.io.esm.min.js';
+
+const sc = new SockethubClient(io('http://localhost:10550', { path: '/sockethub' }));
+</script>
+```
 
 ## Quick Start
 
 ```javascript
 import SockethubClient from '@sockethub/client';
-import { io } from 'socket.io-client';
 
-const socket = io('http://localhost:10550', { path: '/sockethub' });
-const sc = new SockethubClient(socket);
+// Discover the Socket.IO endpoint from the server's base URL. The fetched
+// service descriptor (API versions, platforms, HTTP actions URL) is kept as
+// sc.descriptor. To supply your own socket instead:
+//   new SockethubClient(io('http://localhost:10550', { path: '/sockethub' }))
+const sc = await SockethubClient.connect('http://localhost:10550', {
+    initTimeoutMs: 5000,
+});
 
 sc.socket.on('message', (msg) => console.log(msg));
+sc.socket.on('ready', (info) => {
+    console.log('Sockethub ready:', info.reason, `API v${info.apiVersion}`,
+        info.platforms.map((p) => ({ id: p.id, apiVersion: p.apiVersion })));
+});
+sc.socket.on('init_error', (e) => {
+    console.warn('Sockethub init issue:', e.error);
+});
+
+// Wait for schema registry, then send a message
+try {
+    await sc.ready();
+    sc.socket.emit('message', {
+        '@context': sc.contextFor('dummy'),
+        type: 'echo',
+        actor: { id: 'test@dummy', type: 'person' },
+        object: { type: 'message', content: 'hello world' }
+    }, (ack) => {
+        if (ack?.error) {
+            console.error('Send failed:', ack.error);
+            return;
+        }
+        console.log('Ack:', ack);
+    });
+} catch (err) {
+    console.error('Sockethub failed to initialize:', err);
+}
 ```
 
 See the [Client Guide](../../docs/client-guide.md) for detailed usage and examples.
 
 ## API
 
-- **`new SockethubClient(socket)`** - Create client instance
-- **`sc.socket.emit(event, data)`** - Send messages
+- **`new SockethubClient(socket, options?)`** - Create client instance with optional init/queue settings
+- **`sc.ready(timeoutMs?)`** - Wait for initialization to complete
+- **`sc.isReady()`** - Check whether client is initialized
+- **`sc.getInitState()`** - Return `"idle" | "initializing" | "ready" | "init_error" | "closed"`
+- **`sc.contextFor(platform)`** - Build canonical `@context` for a platform from server registry
+- **`sc.getRegisteredPlatforms()`** - Get server-registered platforms/contexts
+- **`sc.getRegisteredBaseContexts()`** - Get AS2 and Sockethub base context URLs
+- **`sc.getPlatformSchema(platform, schemaType?)`** - Get platform JSON schema
+- **`sc.validateActivity(activity)`** - Validate against registered schemas
+- **`sc.socket.emit(event, data, callback)`** - Send messages (queued until ready)
 - **`sc.socket.on(event, handler)`** - Listen for messages
 - **`sc.clearCredentials()`** - Clear stored credentials
-- **`sc.ActivityStreams`** - ActivityStreams library
+
+Send a full `actor` object on each `credentials` and `message` event.
+
+## Result Handling
+
+For client-initiated requests, pass a callback to `emit` and treat an `error`
+field as failure:
+
+```javascript
+sc.socket.emit("message", {
+    type: "echo",
+    "@context": sc.contextFor("dummy"),
+    actor: { id: "test", type: "person" },
+    object: { type: "message", content: "Hello!" },
+}, (result) => {
+    if (result?.error) {
+        console.error("Sockethub request failed:", result.error);
+        return;
+    }
+
+    console.log("Sockethub request succeeded:", result);
+});
+```
+
+Also listen for ongoing platform events:
+
+```javascript
+sc.socket.on("message", (msg) => {
+    console.log("incoming platform event:", msg);
+});
+```
+
+## Sending messages
+
+Include `id`, `type`, and usually `name` on the `actor` for `credentials` and
+`message` events. Before sending, the client validates each outgoing activity
+against the originating platform's schema from the server registry, surfacing a
+client-side error instead of dispatching a malformed message.
+
+```javascript
+sc.socket.emit("message", {
+    type: "join",
+    "@context": sc.contextFor("irc"),
+    actor: { id: "mynick@irc.libera.chat", type: "person", name: "mynick" },
+    target: {
+        id: "#sockethub@irc.libera.chat",
+        type: "room",
+        name: "#sockethub",
+    },
+}, (result) => {
+    if (result?.error) console.error(result.error);
+});
+```
 
 ## Security & State Management
 
@@ -83,10 +215,14 @@ memory and replaying it when the connection is re-established.
 #### What Gets Stored
 
 - Credentials (passwords, tokens, API keys)
-- Actor definitions
 - Platform connections
 - Channel/room joins
 
+When one of your actors is renamed (an `update` with `object.type: "address"`, such as an IRC nick
+change, whether you requested it and the server acknowledged it or the server reported it), the
+stored entries move to the new actor so a reconnect replays the identity the connection currently
+holds.
+
 #### Storage Location
 
 **All state is stored ONLY in JavaScript memory.** Nothing is persisted to:

package/dist/client-registry.d.ts

@@ -0,0 +1,47 @@
+interface PlatformRegistrySchemas {
+    credentials?: object;
+    messages?: object;
+}
+/**
+ * Server-declared platform metadata used by the client for context generation
+ * and runtime validation.
+ */
+export interface PlatformRegistryEntry {
+    id: string;
+    apiVersion: number;
+    contextUrl: string;
+    contextVersion: string;
+    schemaVersion: string;
+    types: Array<string>;
+    schemas: PlatformRegistrySchemas;
+}
+export interface PlatformRegistryPayload {
+    apiVersion?: number;
+    fingerprint?: string;
+    unchanged?: boolean;
+    contexts?: {
+        as?: string;
+        sockethub?: string;
+    };
+    platforms?: Array<PlatformRegistryEntry>;
+}
+export interface ParsedPlatformRegistry {
+    apiVersion: number;
+    asContextUrl: string;
+    sockethubContextUrl: string;
+    platforms: Map<string, PlatformRegistryEntry>;
+}
+/**
+ * Validate a server `schemas` payload and rebuild it field by field, so
+ * nothing the server sends beyond the bootstrap contract (such as an exact
+ * package version) is retained or re-emitted. Returns undefined for a
+ * malformed payload; malformed platform entries are skipped.
+ */
+export declare function parsePlatformRegistry(payload: unknown): ParsedPlatformRegistry | undefined;
+/**
+ * Register a platform's context and schemas with the @sockethub/schemas
+ * validators so local validation uses the same canonical sources as the
+ * server.
+ */
+export declare function registerPlatformSchemas(platform: PlatformRegistryEntry): void;
+export {};

package/dist/discovery.d.ts

@@ -0,0 +1,30 @@
+import type { ServiceDescriptor } from "@sockethub/schemas";
+import type { ManagerOptions, Socket, SocketOptions } from "socket.io-client";
+/** The `io()` factory exported by `socket.io-client`. */
+export type SocketFactory = (uri: string, opts?: Partial<ManagerOptions & SocketOptions>) => Socket;
+export interface DiscoverOptions {
+    /** Replacement for the global `fetch`, mainly for tests. */
+    fetch?: typeof fetch;
+    /** Abort discovery after this many milliseconds. Default 10000. */
+    discoveryTimeoutMs?: number;
+}
+/** Thrown when a server's descriptor cannot be fetched or is not usable. */
+export declare class DiscoveryError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Fetch and validate a Sockethub server's service descriptor from its base
+ * URL. Every failure rejects with a `DiscoveryError` that says what went
+ * wrong (unreachable, non-JSON, invalid descriptor).
+ */
+export declare function discoverSockethub(baseUrl: string, options?: DiscoverOptions): Promise<ServiceDescriptor>;
+/**
+ * Resolve an advertised endpoint path against the server origin, refusing any
+ * result that lands on another origin. The schema already rejects paths that
+ * URL resolution would read as protocol-relative; this is the belt to that
+ * brace for callers that build URLs from descriptor values.
+ */
+export declare function resolveEndpoint(serverOrigin: string, path: string): string;
+export declare function resolveSocketFactory(explicit?: SocketFactory): Promise<SocketFactory>;

package/dist/replay-store.d.ts

@@ -0,0 +1,44 @@
+import type { ActivityStream } from "@sockethub/schemas";
+export interface EventMapping {
+    credentials: Map<string, ActivityStream>;
+    connect: Map<string, ActivityStream>;
+    join: Map<string, ActivityStream>;
+}
+/**
+ * True for the `{ error }` object the server acks a failed job with.
+ */
+export declare function isErrorResult(value: unknown): boolean;
+/**
+ * Type guard to check if an object is an ActivityStream with a valid actor.id.
+ */
+export declare function hasActorId(obj: ActivityStream): obj is ActivityStream;
+/**
+ * True for the activity that reports or requests a nick change: an
+ * `update` whose object is an `address`, with `actor` the old identity
+ * and `target` the new one.
+ */
+export declare function isActorRename(activity: ActivityStream): boolean;
+/**
+ * In-memory storage for client state that should be replayed on reconnection.
+ *
+ * Security: Stored ONLY in JavaScript heap memory. Never persisted to disk,
+ * localStorage, or any permanent storage. Cleared on page reload.
+ */
+export declare class ReplayStore {
+    readonly events: EventMapping;
+    recordCredentials(content: ActivityStream): void;
+    /**
+     * Stores connect/join commands and drops them again on
+     * disconnect/leave, so a reconnect replays only what is still live.
+     */
+    recordMessage(content: ActivityStream): void;
+    /**
+     * Re-keys every stored entry for the rename's `actor` on its platform to
+     * its `target`. The credential object itself is left as the application
+     * sent it: the server keys the live connection on a fingerprint of that
+     * object, and the worker accepts the hash it was authorized with, so
+     * replaying the original object under the new actor is what lands back
+     * on the renamed connection. Returns the ids moved, for logging.
+     */
+    moveActor(rename: ActivityStream): Array<[string, string]>;
+}