Skip to main content

​
@stoneforge/shared-routes

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.
Reusable Routes: Used by both quarry-server and smithy-server to share API surface.

​
Installation

npm install @stoneforge/shared-routes
Includes hono, @stoneforge/core, and @stoneforge/storage as dependencies.

​
Quick Start

import { Hono } from 'hono';
import {
  createElementsRoutes,
  createEntityRoutes,
  createChannelRoutes,
} from '@stoneforge/shared-routes';
import { createStorage, initializeSchema } from '@stoneforge/storage';
import { createQuarryAPI } from '@stoneforge/quarry/api';

const storage = createStorage({ path: './data.db' });
initializeSchema(storage);
const api = createQuarryAPI(storage);

const app = new Hono();

// Mount route groups
app.route('/api/elements', createElementsRoutes({ api }));
app.route('/api/entities', createEntityRoutes({ api }));
app.route('/api/channels', createChannelRoutes({ api }));

export default app;

​
Route Factories

​
Elements Routes

CRUD operations for all element types. 
import { createElementsRoutes } from '@stoneforge/shared-routes';

const elementsRoutes = createElementsRoutes({ api });
app.route('/api/elements', elementsRoutes);

​
Entity Routes

Entity registration and lookup. 
import { createEntityRoutes } from '@stoneforge/shared-routes';

const entityRoutes = createEntityRoutes({ api });
app.route('/api/entities', entityRoutes);

​
Task Routes

Task CRUD and assignment. 
import { createTaskRoutes } from '@stoneforge/shared-routes';

const taskRoutes = createTaskRoutes({ api });
app.route('/api/tasks', taskRoutes);

​
Channel Routes

Channel creation, membership, and listing. 
import { createChannelRoutes } from '@stoneforge/shared-routes';

const channelRoutes = createChannelRoutes({ api });
app.route('/api/channels', channelRoutes);

​
Message Routes

Send and query messages. 
import { createMessageRoutes } from '@stoneforge/shared-routes';

const messageRoutes = createMessageRoutes({ api });
app.route('/api/messages', messageRoutes);

​
Plan Routes

Plan creation and status tracking. 
import { createPlanRoutes } from '@stoneforge/shared-routes';

const planRoutes = createPlanRoutes({ api });
app.route('/api/plans', planRoutes);

​
Document Routes

Document versioning and content. 
import { createDocumentRoutes } from '@stoneforge/shared-routes';

const documentRoutes = createDocumentRoutes({ api });
app.route('/api/documents', documentRoutes);

​
Library Routes

Library and playbook management. 
import { createLibraryRoutes } from '@stoneforge/shared-routes';

const libraryRoutes = createLibraryRoutes({ api });
app.route('/api/libraries', libraryRoutes);

​
Inbox Routes

Per-entity notification inbox. 
import { createInboxRoutes } from '@stoneforge/shared-routes';
import { createInboxService } from '@stoneforge/quarry';

const inboxService = createInboxService(storage, api);
const inboxRoutes = createInboxRoutes({ api, inbox: inboxService });
app.route('/api/inbox', inboxRoutes);

​
WebSocket Support

Real-time event broadcasting. 
import { 
  EventBroadcaster, 
  initializeBroadcaster, 
  getBroadcaster 
} from '@stoneforge/shared-routes';

const broadcaster = initializeBroadcaster(api);

// Subscribe to events
broadcaster.on('task_created', (task) => {
  console.log('Task created:', task.id);
});

// Broadcast an event
broadcaster.broadcast({
  type: 'task_updated',
  data: task,
});

​
Service Types

​
CollaborateServices

Minimal services object for route factories. 
interface CollaborateServices {
  api: QuarryLikeAPI;
  inbox?: InboxLikeService;
}

interface CollaborateServicesWithBroadcast extends CollaborateServices {
  broadcast: BroadcastInboxEventFn;
}

type BroadcastInboxEventFn = (event: BroadcastEvent) => void;

​
QuarryLikeAPI

Minimal API interface required by route factories. 
interface QuarryLikeAPI {
  get<T>(id: ElementId, options?: GetOptions): Promise<T | null>;
  list<T>(filter?: ElementFilter): Promise<T[]>;
  create<T>(input: ElementInput): Promise<T>;
  update<T>(id: ElementId, updates: Partial<T>, options?: UpdateOptions): Promise<T>;
  delete(id: ElementId, options?: DeleteOptions): Promise<void>;
  // ... (subset of QuarryAPI)
}

​
Error Handling

All route factories include standardized error handling. 
{
  error: {
    code: 'NOT_FOUND',
    message: 'Task not found',
    details: { id: 'el-123' }
  }
}

​
Middleware

Route factories support Hono middleware. 
import { cors } from 'hono/cors';

app.use('/api/*', cors({
  origin: 'http://localhost:5173',
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
}));

​
Example Server

import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { logger } from 'hono/logger';
import {
  createElementsRoutes,
  createEntityRoutes,
  createTaskRoutes,
  createChannelRoutes,
  createMessageRoutes,
  createDocumentRoutes,
  createPlanRoutes,
  createInboxRoutes,
  initializeBroadcaster,
} from '@stoneforge/shared-routes';
import { createStorage, initializeSchema } from '@stoneforge/storage';
import { createQuarryAPI } from '@stoneforge/quarry/api';
import { createInboxService } from '@stoneforge/quarry';

// Setup
const storage = createStorage({ path: '.stoneforge/db.sqlite' });
initializeSchema(storage);
const api = createQuarryAPI(storage);
const inbox = createInboxService(storage, api);
const broadcaster = initializeBroadcaster(api);

const services = { api, inbox, broadcast: (e) => broadcaster.broadcast(e) };

// App
const app = new Hono();

// Middleware
app.use('*', logger());
app.use('/api/*', cors());

// Routes
app.route('/api/elements', createElementsRoutes(services));
app.route('/api/entities', createEntityRoutes(services));
app.route('/api/tasks', createTaskRoutes(services));
app.route('/api/channels', createChannelRoutes(services));
app.route('/api/messages', createMessageRoutes(services));
app.route('/api/documents', createDocumentRoutes(services));
app.route('/api/plans', createPlanRoutes(services));
app.route('/api/inbox', createInboxRoutes(services));

// Health check
app.get('/health', (c) => c.json({ status: 'ok' }));

export default app;

​
Entry Points

import { 
  createElementsRoutes, 
  createEntityRoutes,
  createTaskRoutes,
  EventBroadcaster
} from '@stoneforge/shared-routes';

​
API Reference

​
Route Factory Functions

FunctionSignatureDescription
createElementsRoutes(services: CollaborateServices) => HonoCRUD for all elements
createEntityRoutes(services: CollaborateServices) => HonoEntity management
createTaskRoutes(services: CollaborateServices) => HonoTask operations
createChannelRoutes(services: CollaborateServices) => HonoChannel management
createMessageRoutes(services: CollaborateServices) => HonoMessage sending
createDocumentRoutes(services: CollaborateServices) => HonoDocument operations
createLibraryRoutes(services: CollaborateServices) => HonoLibrary management
createPlanRoutes(services: CollaborateServices) => HonoPlan operations
createInboxRoutes(services: CollaborateServices) => HonoInbox management

​
Broadcaster Functions

FunctionSignatureDescription
initializeBroadcaster(api: QuarryLikeAPI) => EventBroadcasterCreate broadcaster
getBroadcaster() => EventBroadcasterGet singleton
Hono Framework: All route factories return Hono app instances. Hono is a fast, lightweight web framework that works with Bun, Node.js, Deno, and Cloudflare Workers.

​
Next Steps

Quarry API

Understand the underlying API

UI Package

Build a front-end for your server

Build docs developers (and LLMs) love

Get started for freeTalk to us