@hatk/hatk 0.0.1-alpha.3 → 0.0.1-alpha.30

package/dist/xrpc.d.ts

@@ -1,14 +1,25 @@
 import type { Row, FlatRow } from './lex-types.ts';
 export type { Row, FlatRow };
+/** Thrown from XRPC handlers to return a 400 response with an error message. */
 export declare class InvalidRequestError extends Error {
     status: number;
     errorName?: string;
     constructor(message: string, errorName?: string);
 }
+/** Thrown from XRPC handlers to return a 404 response. */
 export declare class NotFoundError extends InvalidRequestError {
     status: number;
     constructor(message?: string);
 }
+/**
+ * Context passed to every XRPC handler. Provides database access, pagination
+ * helpers, viewer auth, record resolution, full-text search, label queries,
+ * and blob URL generation.
+ *
+ * @typeParam P - Query parameter types (derived from lexicon)
+ * @typeParam Records - Map of collection NSID → record type (from generated types)
+ * @typeParam I - Input body type for procedure calls
+ */
 export interface XrpcContext<P = Record<string, string>, Records extends Record<string, any> = Record<string, any>, I = unknown> {
     db: {
         query: (sql: string, params?: any[]) => Promise<any[]>;
@@ -43,11 +54,36 @@ export interface XrpcContext<P = Record<string, string>, Records extends Record<
     labels: (uris: string[]) => Promise<Map<string, any[]>>;
     blobUrl: (did: string, ref: unknown, preset?: 'avatar' | 'banner' | 'feed_thumbnail' | 'feed_fullsize') => string | undefined;
 }
+/** Set the relay URL used for blob URL generation. Called once during boot. */
 export declare function configureRelay(relay: string): void;
+/**
+ * Generate a CDN URL for a blob ref. Uses the PDS directly in local dev,
+ * or the Bluesky CDN (`cdn.bsky.app`) in production.
+ */
 export declare function blobUrl(did: string, ref: unknown, preset?: 'avatar' | 'banner' | 'feed_thumbnail' | 'feed_fullsize'): string | undefined;
+/**
+ * Discover and load XRPC handler modules from the `xrpc/` directory.
+ * Directory nesting maps to NSID segments. Parameters are validated and
+ * coerced against the matching lexicon definition.
+ */
 export declare function initXrpc(xrpcDir: string): Promise<void>;
+/** Register a single XRPC handler from a scanned server/ module. */
+export declare function registerXrpcHandler(nsid: string, handlerModule: {
+    handler: (ctx: any) => Promise<any>;
+}): void;
+/** Execute a registered XRPC handler by name. Returns null if no handler matches. */
 export declare function executeXrpc(name: string, params: Record<string, string>, cursor: string | undefined, limit: number, viewer?: {
     did: string;
 } | null, input?: unknown): Promise<any | null>;
+/** Call a registered XRPC handler directly (no HTTP). For use in SSR renderers. */
+export declare function callXrpc(nsid: string, params?: Record<string, any>, input?: unknown): Promise<any>;
+/**
+ * Register a core XRPC handler directly (no XrpcContext wrapping).
+ * Used for built-in dev.hatk.* handlers that manage their own dependencies.
+ */
+export declare function registerCoreXrpcHandler(nsid: string, fn: (params: Record<string, string>, cursor: string | undefined, limit: number, viewer: {
+    did: string;
+} | null, input?: unknown) => Promise<any>): void;
+/** Return all registered XRPC method names. */
 export declare function listXrpc(): string[];
 //# sourceMappingURL=xrpc.d.ts.map

package/dist/xrpc.d.ts.map

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

package/dist/xrpc.js

@@ -6,12 +6,33 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+/**
+ * XRPC method handler system for serving AT Protocol endpoints.
+ *
+ * Place handler modules in the `xrpc/` directory, nested by NSID segments
+ * (e.g. `xrpc/app/bsky/feed/getAuthorFeed.ts` → `app.bsky.feed.getAuthorFeed`).
+ * Each module default-exports a `{ handler }` function that receives an
+ * {@link XrpcContext} with database access, query params, pagination, and
+ * viewer auth.
+ *
+ * @example
+ * ```ts
+ * // xrpc/xyz/statusphere/getStatuses.ts
+ * import { defineXrpc } from '../../hatk.generated.ts'
+ *
+ * export default defineXrpc('xyz.statusphere.getStatuses', async (ctx) => {
+ *   const rows = await ctx.db.query('SELECT * FROM statusphere_status LIMIT ?', [ctx.limit])
+ *   return { statuses: rows }
+ * })
+ * ```
+ */
 import { resolve, relative } from 'node:path';
 import { readdirSync, statSync } from 'node:fs';
 import { log } from "./logger.js";
-import { querySQL, runSQL, packCursor, unpackCursor, isTakendownDid, filterTakendownDids, searchRecords, findUriByFields, lookupByFieldBatch, countByFieldBatch, queryLabelsForUris, } from "./db.js";
+import { querySQL, runSQL, packCursor, unpackCursor, isTakendownDid, filterTakendownDids, searchRecords, findUriByFields, lookupByFieldBatch, countByFieldBatch, queryLabelsForUris, } from "./database/db.js";
 import { resolveRecords } from "./hydrate.js";
-import { getLexicon } from "./schema.js";
+import { getLexicon } from "./database/schema.js";
+/** Thrown from XRPC handlers to return a 400 response with an error message. */
 export class InvalidRequestError extends Error {
     status = 400;
     errorName;
@@ -20,6 +41,7 @@ export class InvalidRequestError extends Error {
         this.errorName = errorName;
     }
 }
+/** Thrown from XRPC handlers to return a 404 response. */
 export class NotFoundError extends InvalidRequestError {
     status = 404;
     constructor(message = 'Not found') {
@@ -27,9 +49,14 @@ export class NotFoundError extends InvalidRequestError {
     }
 }
 let _relayUrl = '';
+/** Set the relay URL used for blob URL generation. Called once during boot. */
 export function configureRelay(relay) {
     _relayUrl = relay;
 }
+/**
+ * Generate a CDN URL for a blob ref. Uses the PDS directly in local dev,
+ * or the Bluesky CDN (`cdn.bsky.app`) in production.
+ */
 export function blobUrl(did, ref, preset = 'avatar') {
     if (!ref)
         return undefined;
@@ -42,6 +69,7 @@ export function blobUrl(did, ref, preset = 'avatar') {
     return `https://cdn.bsky.app/img/${preset}/plain/${did}/${p.ref.$link}@jpeg`;
 }
 const handlers = new Map();
+/** Recursively collect .ts/.js files in a directory, skipping files prefixed with `_`. */
 function walkDir(dir) {
     const results = [];
     try {
@@ -58,6 +86,11 @@ function walkDir(dir) {
     catch { }
     return results.sort();
 }
+/**
+ * Discover and load XRPC handler modules from the `xrpc/` directory.
+ * Directory nesting maps to NSID segments. Parameters are validated and
+ * coerced against the matching lexicon definition.
+ */
 export async function initXrpc(xrpcDir) {
     const files = walkDir(xrpcDir);
     if (files.length === 0)
@@ -65,7 +98,7 @@ export async function initXrpc(xrpcDir) {
     for (const scriptPath of files) {
         const rel = relative(xrpcDir, scriptPath).replace(/\.(ts|js)$/, '');
         const name = rel.replace(/[\\/]/g, '.');
-        const mod = await import(__rewriteRelativeImportExtension(scriptPath));
+        const mod = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ `${scriptPath}?t=${Date.now()}`));
         const handler = mod.default;
         // Extract param schema from lexicon for validation and defaults
         const lexicon = getLexicon(name);
@@ -128,12 +161,100 @@ export async function initXrpc(xrpcDir) {
         log(`[xrpc] discovered: ${name}`);
     }
 }
+/** Register a single XRPC handler from a scanned server/ module. */
+export function registerXrpcHandler(nsid, handlerModule) {
+    const lexicon = getLexicon(nsid);
+    const paramsDef = lexicon?.defs?.main?.parameters;
+    const requiredParams = paramsDef?.required || [];
+    const paramProperties = paramsDef?.properties || {};
+    handlers.set(nsid, {
+        name: nsid,
+        execute: async (params, cursor, limit, viewer, input) => {
+            for (const [key, def] of Object.entries(paramProperties)) {
+                if (params[key] == null && def.default != null) {
+                    params[key] = String(def.default);
+                }
+                if (params[key] != null && def.type === 'integer') {
+                    params[key] = Number(params[key]);
+                }
+            }
+            for (const param of requiredParams) {
+                if (!params[param]) {
+                    throw new InvalidRequestError(`Missing required parameter: ${param}`, 'InvalidRequest');
+                }
+            }
+            const ctx = {
+                db: { query: querySQL, run: runSQL },
+                params,
+                input: input || {},
+                cursor,
+                limit,
+                viewer,
+                packCursor,
+                unpackCursor,
+                isTakendown: isTakendownDid,
+                filterTakendownDids,
+                search: searchRecords,
+                resolve: resolveRecords,
+                lookup: async (collection, field, values) => {
+                    if (values.length === 0)
+                        return new Map();
+                    const unique = [...new Set(values.filter(Boolean))];
+                    return lookupByFieldBatch(collection, field, unique);
+                },
+                count: async (collection, field, values) => {
+                    if (values.length === 0)
+                        return new Map();
+                    const unique = [...new Set(values.filter(Boolean))];
+                    return countByFieldBatch(collection, field, unique);
+                },
+                exists: async (collection, filters) => {
+                    const conditions = Object.entries(filters).map(([field, value]) => ({ field, value }));
+                    const uri = await findUriByFields(collection, conditions);
+                    return uri !== null;
+                },
+                labels: queryLabelsForUris,
+                blobUrl,
+            };
+            return handlerModule.handler(ctx);
+        },
+    });
+}
+/** Execute a registered XRPC handler by name. Returns null if no handler matches. */
 export async function executeXrpc(name, params, cursor, limit, viewer, input) {
     const handler = handlers.get(name);
     if (!handler)
         return null;
     return handler.execute(params, cursor, limit, viewer || null, input);
 }
+/** Call a registered XRPC handler directly (no HTTP). For use in SSR renderers. */
+export async function callXrpc(nsid, params = {}, input) {
+    const viewer = globalThis.__hatk_viewer ?? null;
+    // In externalized module context (e.g. SSR), delegate to the runner's callXrpc via globalThis.
+    // The runner's module instance has all registered handlers; this (Node's) instance may not.
+    if (handlers.size === 0 && globalThis.__hatk_callXrpc) {
+        return globalThis.__hatk_callXrpc(nsid, params, input);
+    }
+    const stringParams = {};
+    for (const [k, v] of Object.entries(params)) {
+        if (v != null)
+            stringParams[k] = String(v);
+    }
+    const limit = params.limit ? Number(params.limit) : 20;
+    const cursor = params.cursor ?? undefined;
+    const result = await executeXrpc(nsid, stringParams, cursor, limit, viewer, input);
+    if (result === null)
+        throw new Error(`No XRPC handler registered for ${nsid}`);
+    return result;
+}
+/**
+ * Register a core XRPC handler directly (no XrpcContext wrapping).
+ * Used for built-in dev.hatk.* handlers that manage their own dependencies.
+ */
+export function registerCoreXrpcHandler(nsid, fn) {
+    handlers.set(nsid, { name: nsid, execute: fn });
+}
+/** Return all registered XRPC method names. */
 export function listXrpc() {
     return Array.from(handlers.keys());
 }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@hatk/hatk",
-  "version": "0.0.1-alpha.3",
+  "version": "0.0.1-alpha.30",
+  "license": "MIT",
   "bin": {
     "hatk": "dist/cli.js"
   },
@@ -19,10 +20,12 @@
     "./xrpc-client": "./dist/xrpc-client.js",
     "./views": "./dist/views.js",
     "./seed": "./dist/seed.js",
+    "./hooks": "./dist/hooks.js",
     "./setup": "./dist/setup.js",
     "./test": "./dist/test.js",
-    "./test/browser": "./dist/test-browser.js",
-    "./vite-plugin": "./dist/vite-plugin.js"
+    "./config": "./dist/config.js",
+    "./vite-plugin": "./dist/vite-plugin.js",
+    "./renderer": "./dist/renderer.js"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -33,13 +36,17 @@
     "@duckdb/node-api": "^1.4.4-r.1",
     "@hatk/oauth-client": "*",
     "@resvg/resvg-js": "^2.6.2",
+    "better-sqlite3": "^12.6.2",
     "satori": "^0.19.2",
     "vitest": "^4",
     "yaml": "^2.7.0"
   },
+  "peerDependencies": {
+    "vite": "^8.0.0"
+  },
   "devDependencies": {
-    "@playwright/test": "^1.58.2",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/react": "^19.2.14",
-    "vite": "^6"
+    "vite": "^8.0.0"
   }
 }