@rgby/collab-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Hocuspocus Module SDK
+ *
+ * Types and helpers for building distributable modules.
+ */
+import type { Extension } from "@hocuspocus/server";
+import type { Hono } from "hono";
+export interface ModuleManifest {
+    /** Unique module identifier (reverse domain notation) */
+    id: string;
+    /** Semantic version */
+    version: string;
+    /** Display name */
+    name?: string;
+    /** Description */
+    description?: string;
+    /** What this module contributes */
+    contributes: ModuleContributions;
+    /** Required permissions */
+    permissions?: ModulePermissions;
+    /** Module dependencies (other module IDs) */
+    dependencies?: string[];
+}
+export interface ModuleContributions {
+    hocuspocus?: boolean;
+    workers?: boolean;
+    events?: string[];
+    routes?: boolean;
+}
+export interface ModulePermissions {
+    events?: ('emit' | 'subscribe')[];
+    workers?: ('cpu' | 'io' | 'network')[];
+}
+export interface WorkerInput<T = unknown> {
+    taskId: string;
+    moduleId: string;
+    payload: T;
+    context: {
+        timestamp: string;
+        requestId?: string;
+    };
+}
+export interface WorkerEffect {
+    type: 'emit' | 'schedule' | 'noop';
+    event?: string;
+    payload?: unknown;
+    taskId?: string;
+    delay?: number;
+}
+export interface WorkerTask<TInput = unknown> {
+    id: string;
+    handler: (input: WorkerInput<TInput>) => Promise<WorkerEffect | WorkerEffect[]>;
+    priority?: number;
+    timeout?: number;
+}
+export type EventHandler<T = unknown> = (payload: T) => void | Promise<void>;
+export interface EventSubscription {
+    event: string;
+    handler: EventHandler;
+    filter?: (payload: unknown) => boolean;
+}
+export type ModuleRouteFactory = (router: Hono) => void;
+export interface ModuleDefinition {
+    manifest: ModuleManifest;
+    hocuspocus?: Extension;
+    workers?: WorkerTask[];
+    events?: EventSubscription[];
+    routes?: ModuleRouteFactory;
+    /**
+     * Client-side TipTap extensions
+     * These will be dynamically loaded on the client.
+     */
+    clientExtensions?: TipTapExtensionDefinition[];
+    /**
+     * Services/APIs exported by this module for other modules to use.
+     */
+    exports?: Record<string, any>;
+    /**
+     * Database extensions
+     */
+    database?: {
+        /** SQL Migrations */
+        migrations?: MigrationDefinition[];
+    };
+    /**
+     * Lifecycle hooks
+     */
+    hooks?: ModuleHooks;
+    /**
+     * Global middleware to inject
+     */
+    middleware?: ModuleMiddleware[];
+}
+export interface TipTapExtensionDefinition {
+    name: string;
+    options?: Record<string, any>;
+    /** Absolute path to the extension script file on the server */
+    scriptPath?: string;
+    /** Public URL to load the script from (populated by server) */
+    scriptUrl?: string;
+}
+export interface ModuleHooks {
+    /** Called when module is initialized (before server start) */
+    onInit?: (context: ModuleContext) => Promise<void> | void;
+    /** Called when server has started (Hono & Hocuspocus ready) */
+    onServerStart?: (app: Hono, hocuspocus: Extension) => Promise<void> | void;
+    /** Called when server is stopping */
+    onServerStop?: () => Promise<void> | void;
+    /** Called when a user connects (Hocuspocus event) */
+    onUserConnect?: (data: any) => Promise<void> | void;
+}
+export interface ModuleMiddleware {
+    path: string;
+    handler: (c: any, next: any) => Promise<void> | Response | Promise<Response>;
+}
+export interface ServiceRegistry {
+    /** Get a service exported by another module */
+    get<T = any>(serviceName: string): T | undefined;
+}
+export interface MigrationDefinition {
+    version: number;
+    up: string;
+    down?: string;
+}
+export interface ModuleContext {
+    /** Module's own ID */
+    moduleId: string;
+    /** Emit an event (if permitted) */
+    emit: (event: string, payload: unknown) => void;
+    /** Schedule a worker task */
+    schedule: (taskId: string, payload: unknown, delay?: number) => void;
+    /** Get logger scoped to this module */
+    log: ModuleLogger;
+    /** Access to the database instance */
+    db: any;
+    /** Read-only server configuration */
+    config: any;
+    /** Access to Hocuspocus instance */
+    hocuspocus: any;
+    /** Service registry to look up other modules' exports */
+    services: ServiceRegistry;
+}
+export interface ModuleLogger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * Define a module with type checking
+ */
+export declare function defineModule(definition: ModuleDefinition): ModuleDefinition;
+/**
+ * Define a worker task with type checking
+ */
+export declare function defineWorkerTask<T = unknown>(task: WorkerTask<T>): WorkerTask<T>;
+/**
+ * Create an emit effect
+ */
+export declare function emit(event: string, payload: unknown): WorkerEffect;
+/**
+ * Create a schedule effect
+ */
+export declare function schedule(taskId: string, payload?: unknown, delay?: number): WorkerEffect;
+/**
+ * Create a noop effect
+ */
+export declare function noop(): WorkerEffect;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Hocuspocus Module SDK
+ *
+ * Types and helpers for building distributable modules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineModule = defineModule;
+exports.defineWorkerTask = defineWorkerTask;
+exports.emit = emit;
+exports.schedule = schedule;
+exports.noop = noop;
+/**
+ * Define a module with type checking
+ */
+function defineModule(definition) {
+    return definition;
+}
+/**
+ * Define a worker task with type checking
+ */
+function defineWorkerTask(task) {
+    return task;
+}
+/**
+ * Create an emit effect
+ */
+function emit(event, payload) {
+    return { type: 'emit', event, payload };
+}
+/**
+ * Create a schedule effect
+ */
+function schedule(taskId, payload, delay) {
+    return { type: 'schedule', taskId, payload, delay };
+}
+/**
+ * Create a noop effect
+ */
+function noop() {
+    return { type: 'noop' };
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+    "name": "@rgby/collab-sdk",
+    "version": "1.0.0",
+    "description": "SDK for building Hocuspocus modules",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "hocuspocus",
+        "module",
+        "sdk",
+        "collaborative",
+        "yjs"
+    ],
+    "peerDependencies": {
+        "@hocuspocus/server": "^2.0.0"
+    },
+    "devDependencies": {
+        "typescript": "^5.0.0",
+        "@hocuspocus/server": "^2.0.0"
+    }
+}