@dotdo/do 0.1.0

package/dist/rpc/routes.d.ts

@@ -0,0 +1,332 @@
+/**
+ * CapnWeb RPC HTTP Route Handlers
+ *
+ * Handles GET requests to /rpc/* for schema discovery and method documentation.
+ * Returns JSON-LD style responses with clickable links for API navigation.
+ *
+ * @module rpc/routes
+ *
+ * @example
+ * ```typescript
+ * import { RPCRouteHandler } from 'do/rpc/routes'
+ * import { MethodRegistry } from 'do/rpc/methods'
+ *
+ * const registry = new MethodRegistry()
+ * // Register methods...
+ *
+ * const handler = new RPCRouteHandler(registry, 'https://my-do.example.com')
+ *
+ * // Handle GET /rpc
+ * const schemaResponse = await handler.handleSchemaRequest()
+ *
+ * // Handle GET /rpc/do.things.list
+ * const methodResponse = await handler.handleMethodRequest('do.things.list')
+ * ```
+ */
+import type { MethodRegistry } from './methods';
+/**
+ * JSON-LD style link
+ */
+export interface Link {
+    /** Link relation type */
+    rel: string;
+    /** Target URL */
+    href: string;
+    /** HTTP method (if not GET) */
+    method?: string;
+    /** Link title */
+    title?: string;
+}
+/**
+ * Schema response for GET /rpc
+ */
+export interface SchemaResponse {
+    /** JSON-LD ID */
+    $id: string;
+    /** JSON-LD type */
+    $type: 'RPCSchema';
+    /** Methods grouped by namespace (legacy) */
+    methods?: Record<string, NamespaceInfo>;
+    /** Namespaces with their methods */
+    namespaces: Record<string, NamespaceInfo>;
+    /** Quick links to common operations */
+    links: Link[];
+    /** Total number of methods */
+    methodCount: number;
+}
+/**
+ * Namespace information
+ */
+export interface NamespaceInfo {
+    /** Link to namespace documentation */
+    $ref: string;
+    /** Available methods in this namespace */
+    methods: string[];
+    /** Description */
+    description?: string;
+}
+/**
+ * Example request/response for method documentation
+ */
+export interface MethodExample {
+    /** Example request body */
+    request: unknown;
+    /** Example response body */
+    response: unknown;
+}
+/**
+ * Method documentation response
+ */
+export interface MethodResponse {
+    /** JSON-LD ID */
+    $id: string;
+    /** JSON-LD type */
+    $type: 'RPCMethod';
+    /** Full method name */
+    name: string;
+    /** Method description */
+    description?: string;
+    /** Parameter documentation */
+    params?: Record<string, ParamDoc> | null;
+    /** Return type */
+    returns?: string;
+    /** Related links */
+    links: Link[];
+    /** Example request/response */
+    example?: MethodExample;
+}
+/**
+ * Parameter documentation
+ */
+export interface ParamDoc {
+    /** Parameter type */
+    type: string;
+    /** Whether required */
+    required?: boolean;
+    /** Description */
+    description?: string;
+    /** Default value */
+    default?: unknown;
+}
+/**
+ * Namespace documentation response
+ */
+export interface NamespaceResponse {
+    /** JSON-LD ID */
+    $id: string;
+    /** JSON-LD type */
+    $type: 'RPCNamespace';
+    /** Namespace name (full, e.g., 'do.identity') */
+    name: string;
+    /** Namespace short name (e.g., 'identity') */
+    namespace: string;
+    /** Description */
+    description?: string;
+    /** Methods in this namespace */
+    methods: MethodSummary[];
+    /** Navigation links */
+    links: Link[];
+}
+/**
+ * Method summary for namespace listing
+ */
+export interface MethodSummary {
+    /** Method name (action part only) */
+    name: string;
+    /** Full method name */
+    fullName: string;
+    /** Link to method documentation */
+    href: string;
+    /** Description */
+    description?: string;
+}
+/**
+ * Collections listing response
+ */
+export interface CollectionsResponse {
+    /** JSON-LD ID */
+    $id: string;
+    /** JSON-LD type */
+    $type: 'RPCMethod';
+    /** Method name */
+    name: 'do.collections.list';
+    /** Description */
+    description: string;
+    /** Return type */
+    returns: 'string[]';
+    /** Available collections */
+    collections: CollectionInfo[];
+}
+/**
+ * Collection operation links
+ */
+export interface CollectionLinks {
+    /** Link to list method */
+    list?: string;
+    /** Link to get method */
+    get?: string;
+    /** Link to create method */
+    create?: string;
+    /** Link to update method */
+    update?: string;
+    /** Link to delete method */
+    delete?: string;
+}
+/**
+ * Collection information
+ */
+export interface CollectionInfo {
+    /** Collection name */
+    name: string;
+    /** Link to collection namespace */
+    href: string;
+    /** Available operations */
+    operations?: string[];
+    /** Links to individual operations */
+    links?: CollectionLinks;
+}
+/**
+ * Handler for /rpc/* GET routes
+ *
+ * Generates JSON-LD style responses with clickable links for navigating
+ * the RPC API through a browser.
+ *
+ * @example
+ * ```typescript
+ * const handler = new RPCRouteHandler(registry, 'https://my-do.example.com')
+ *
+ * // In fetch handler:
+ * const url = new URL(request.url)
+ * if (request.method === 'GET' && url.pathname.startsWith('/rpc')) {
+ *   return handler.handleRequest(url.pathname)
+ * }
+ * ```
+ */
+export declare class RPCRouteHandler {
+    private registry;
+    private baseUrl;
+    /**
+     * Create a new route handler
+     *
+     * @param registry - Method registry for introspection
+     * @param baseUrl - Base URL for generating absolute links
+     */
+    constructor(registry: MethodRegistry, baseUrl: string);
+    /**
+     * Handle a GET request to /rpc/*
+     *
+     * Routes to appropriate handler based on path:
+     * - /rpc - Schema overview
+     * - /rpc/do.{namespace} - Namespace documentation
+     * - /rpc/do.{namespace}.{action} - Method documentation
+     * - /rpc/do.collections.list - Collections listing (special case)
+     *
+     * @param request - HTTP Request object or path string
+     * @returns HTTP Response with JSON body
+     */
+    handleRequest(request: Request | string): Response | Promise<Response>;
+    /**
+     * Generate schema overview response
+     */
+    handleSchemaRequest(): SchemaResponse;
+    /**
+     * Generate namespace documentation response
+     */
+    handleNamespaceRequest(namespace: string): NamespaceResponse | null;
+    /**
+     * Generate method documentation response
+     */
+    handleMethodRequest(method: string): MethodResponse | null;
+    /**
+     * Generate collections listing response
+     */
+    handleCollectionsRequest(): CollectionsResponse;
+    /**
+     * Generate links for a method
+     */
+    private generateMethodLinks;
+    /**
+     * Generate links for a namespace
+     */
+    private generateNamespaceLinks;
+    /**
+     * Generate common links for schema root
+     */
+    private generateSchemaLinks;
+    /**
+     * Build absolute URL from path
+     */
+    private buildUrl;
+    /**
+     * Create JSON response
+     */
+    private jsonResponse;
+    /**
+     * Create HTML response
+     */
+    private htmlResponse;
+    /**
+     * Render data as HTML with clickable links
+     */
+    private renderHtml;
+    /**
+     * Create 404 response
+     */
+    private notFound;
+    /**
+     * Create 404 response with suggestions for similar methods
+     */
+    private notFoundWithSuggestions;
+    /**
+     * Find methods similar to the given path (for suggestions)
+     */
+    private findSimilarMethods;
+    /**
+     * Simple string similarity (0-1)
+     */
+    private similarity;
+    /**
+     * Handle POST invocation of a method
+     */
+    private handlePostInvocation;
+    /**
+     * Generate CORS headers
+     */
+    private corsHeaders;
+}
+/**
+ * Create a route handler
+ *
+ * @param registry - Method registry
+ * @param baseUrl - Base URL for links
+ * @returns Configured route handler
+ */
+export declare function createRouteHandler(registry: MethodRegistry, baseUrl: string): RPCRouteHandler;
+/**
+ * Standard collection names
+ *
+ * Used for generating collection links.
+ */
+export declare const STANDARD_COLLECTIONS: readonly ["nouns", "verbs", "things", "actions", "relationships", "functions", "workflows", "events", "experiments", "orgs", "roles", "users", "agents", "integrations", "webhooks"];
+/**
+ * Standard collection operations
+ *
+ * Common CRUD operations available on collections.
+ */
+export declare const COLLECTION_OPERATIONS: readonly ["list", "get", "create", "update", "delete"];
+/**
+ * Create a method link URL
+ *
+ * @param baseUrl - Base URL for the API
+ * @param method - Method name (e.g., 'do.things.list')
+ * @param isNamespace - Whether this is a namespace link (default: false)
+ * @returns Full URL to the method or namespace
+ *
+ * @example
+ * ```typescript
+ * const link = createMethodLink('https://example.com', 'do.things.list')
+ * // Returns: 'https://example.com/rpc/do.things.list'
+ * ```
+ */
+export declare function createMethodLink(baseUrl: string, method: string, isNamespace?: boolean): string;
+//# sourceMappingURL=routes.d.ts.map

package/dist/rpc/routes.d.ts.map

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