@stoneforge/shared-routes

Hono route factories for building Stoneforge-compatible HTTP servers.

Overview

@stoneforge/shared-routes provides pre-built Hono route factories that expose the Stoneforge data model over HTTP. Each factory returns a Hono app instance that can be mounted at any path. The package also includes WebSocket utilities for real-time event broadcasting. Used by quarry-server and smithy-server to share API surface.

Installation

npm install @stoneforge/shared-routes

Requires hono as a dependency (included).

Quick Start

import { Hono } from 'hono';
import {
  createElementsRoutes,
  createEntityRoutes,
  createChannelRoutes,
  createMessageRoutes,
} from '@stoneforge/shared-routes';

const app = new Hono();

// Mount route groups
app.route('/api/elements', createElementsRoutes(services));
app.route('/api/entities', createEntityRoutes(services));
app.route('/api/channels', createChannelRoutes(services));
app.route('/api/messages', createMessageRoutes(services));

export default app;

Route Factories

| Factory | Endpoints | |---------|-----------| | createElementsRoutes(services) | CRUD for elements (tasks, documents, etc.) | | createEntityRoutes(services) | Entity registration and lookup | | createChannelRoutes(services) | Channel creation, membership, listing | | createMessageRoutes(services) | Send and query messages | | createLibraryRoutes(services) | Library and playbook management | | createDocumentRoutes(services) | Document versioning and content | | createInboxRoutes(services) | Per-entity notification inbox | | createPlanRoutes(services) | Plan creation and status tracking | | createTaskRoutes(services) | Task CRUD and assignment |

All factories accept a CollaborateServices (or CollaborateServicesWithBroadcast) object that provides the backing QuarryAPI and optional broadcast function.

WebSocket

import { EventBroadcaster, initializeBroadcaster, getBroadcaster } from '@stoneforge/shared-routes';
import type { EventListener } from '@stoneforge/shared-routes';

const broadcaster = initializeBroadcaster(api);
const services: CollaborateServicesWithBroadcast = { api, broadcast: (event) => broadcaster.broadcast(event) };

Part of Stoneforge — Apache-2.0