@hatk/hatk 0.0.1-alpha.11 → 0.0.1-alpha.111

package/dist/xrpc.d.ts

@@ -1,26 +1,42 @@
+import { type SpaceCredential } from './spaces/credential.ts';
+import type { BaseContext } from './hydrate.ts';
 import type { Row, FlatRow } from './lex-types.ts';
+import type { OAuthConfig, CdnConfig } from './config.ts';
+import type { PdsXrpcOptions } from './pds-proxy.ts';
+import { type ObtainedSession } from './oauth/server.ts';
 export type { Row, FlatRow };
+/** Set the OAuth config used for record write helpers. Called once during boot. */
+export declare function configureOAuth(config: OAuthConfig | null): void;
+/** 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);
 }
-export interface XrpcContext<P = Record<string, string>, Records extends Record<string, any> = Record<string, any>, I = unknown> {
+/**
+ * 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> extends BaseContext {
     db: {
-        query: (sql: string, params?: any[]) => Promise<any[]>;
-        run: (sql: string, ...params: any[]) => Promise<void>;
+        query: (sql: string, params?: unknown[]) => Promise<unknown[]>;
+        run: (sql: string, params?: unknown[]) => Promise<void>;
+        unfiltered: (sql: string, params?: unknown[]) => Promise<unknown[]>;
     };
     params: P;
     input: I;
     cursor?: string;
     limit: number;
-    viewer: {
-        did: string;
-    } | null;
     packCursor: (primary: string | number, cid: string) => string;
     unpackCursor: (cursor: string) => {
         primary: string;
@@ -37,17 +53,132 @@ export interface XrpcContext<P = Record<string, string>, Records extends Record<
         cursor?: string;
     }>;
     resolve: <R = unknown>(uris: string[]) => Promise<Row<R>[]>;
-    lookup: <R = any>(collection: string, field: string, values: string[]) => Promise<Map<string, Row<R>>>;
-    count: (collection: string, field: string, values: string[]) => Promise<Map<string, number>>;
     exists: (collection: string, filters: Record<string, string>) => Promise<boolean>;
-    labels: (uris: string[]) => Promise<Map<string, any[]>>;
-    blobUrl: (did: string, ref: unknown, preset?: 'avatar' | 'banner' | 'feed_thumbnail' | 'feed_fullsize') => string | undefined;
+    createRecord: (collection: string, record: Record<string, unknown>, opts?: {
+        rkey?: string;
+    }) => Promise<{
+        uri?: string;
+        cid?: string;
+    }>;
+    putRecord: (collection: string, rkey: string, record: Record<string, unknown>) => Promise<{
+        uri?: string;
+        cid?: string;
+    }>;
+    deleteRecord: (collection: string, rkey: string) => Promise<void>;
+    applyWrites: (writes: Array<{
+        $type: string;
+        collection: string;
+        rkey?: string;
+        value?: Record<string, unknown>;
+    }>) => Promise<{
+        results?: Array<{
+            $type: string;
+            uri?: string;
+            cid?: string;
+        }>;
+    }>;
+    /**
+     * Call any XRPC method on the viewer's PDS with their session. The escape
+     * hatch beside the record helpers above: nothing is validated or indexed, and
+     * the granted scopes still apply. See {@link pdsXrpc}.
+     */
+    pds: (nsid: string, options?: PdsXrpcOptions) => Promise<Record<string, unknown>>;
+    /**
+     * The viewer's own credential for a space, minted with their session and
+     * cached until shortly before it expires. Its `fetch` presents it to any
+     * host in the space, signed for the repo a request names (or the authority).
+     *
+     * For reads an app makes itself, as the viewer, that the index does not
+     * serve. Throws a `SpaceCredentialError` — `status` and `code` are the
+     * authority's — when the viewer may not read the space, and with status 401
+     * when there is no viewer. Pass `refresh` after a host refuses a credential
+     * that had not yet expired.
+     */
+    spaceCredential: (space: string, opts?: {
+        refresh?: boolean;
+    }) => Promise<SpaceCredential>;
+    /**
+     * Drop the viewer's cached credential for a space, after something that may
+     * have changed their standing in it, such as leaving. Does nothing without a
+     * viewer.
+     */
+    forgetSpaceCredential: (space: string) => void;
+    /**
+     * The record helpers and `pds` above, acting as another account this app
+     * holds a session for — one it obtained with {@link obtainSession}, say.
+     * Nothing here checks that the viewer may act for that account: that is the
+     * app's decision, made before calling.
+     */
+    asAccount: (did: string) => AccountHelpers;
+    /**
+     * Obtain a session for another account straight from its authorization
+     * server, outside the redirect flow — a group host creating an account for
+     * this app, for instance. POSTs `body` to `url` as this app's OAuth client,
+     * with DPoP, and stores the session the response carries for its `sub`, so
+     * {@link asAccount} works for it afterwards. See `obtainSession` in
+     * `oauth/server.ts`.
+     */
+    obtainSession: (url: string, body: Record<string, unknown>, opts?: {
+        headers?: Record<string, string>;
+    }) => Promise<ObtainedSession>;
 }
+/** The PDS helpers on {@link XrpcContext}, for one account. */
+export type AccountHelpers = Pick<XrpcContext, 'createRecord' | 'putRecord' | 'deleteRecord' | 'applyWrites' | 'pds'>;
+/** Set the relay URL used for blob URL generation. Called once during boot. */
+/** True when the relay is a loopback URL — a dev PDS rather than the network. */
+export declare function isLocalRelay(): boolean;
 export declare function configureRelay(relay: string): void;
-export declare function blobUrl(did: string, ref: unknown, preset?: 'avatar' | 'banner' | 'feed_thumbnail' | 'feed_fullsize'): string | undefined;
+/** Set the CDN config for imgproxy URL signing. Called once during boot. */
+export declare function configureCdn(cdn: CdnConfig | null): void;
+/**
+ * Generate a CDN URL for a blob ref. Uses the PDS directly in local dev,
+ * a configured imgproxy CDN if available, or the Bluesky CDN as fallback.
+ */
+export declare function blobUrl(did: string, ref: unknown, preset?: string): string | undefined;
+/** Build a full XrpcContext from request parameters. Reuses buildBaseContext for shared fields. */
+export declare function buildXrpcContext(params: XrpcParams, cursor: string | undefined, limit: number, viewer: {
+    did: string;
+    handle?: string;
+} | null, input?: unknown): XrpcContext;
+/**
+ * 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>;
-export declare function executeXrpc(name: string, params: Record<string, string>, cursor: string | undefined, limit: number, viewer?: {
+/** Register a single XRPC handler from a scanned server/ module. */
+export declare function registerXrpcHandler(nsid: string, handlerModule: {
+    handler: (ctx: any) => Promise<any>;
+}): void;
+/**
+ * What the query string gives a handler: one value per key, or every value
+ * when the key was repeated (`?dids=a&dids=b`).
+ */
+export type XrpcParams = Record<string, any>;
+/** Collect a query string into params, keeping every value of a repeated key. */
+export declare function paramsFromSearch(search: URLSearchParams): XrpcParams;
+/**
+ * Apply the lexicon's parameter schema before a handler runs: defaults,
+ * integer coercion, and arrays. A query string cannot say whether
+ * `dids=x` is one string or a one-element list, so the schema decides: a
+ * parameter declared `array` always reaches the handler as one, or a handler
+ * that spreads it would spread the characters of a DID instead.
+ */
+export declare function coerceParams(params: XrpcParams, properties: Record<string, any>, required: string[]): void;
+/** Execute a registered XRPC handler by name. Returns null if no handler matches. */
+export declare function executeXrpc(name: string, params: XrpcParams, 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: XrpcParams, cursor: string | undefined, limit: number, viewer: {
+    did: string;
+    handle?: 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,43 @@ 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 { guardedQuerySQL, unfilteredQuerySQL } from "./spaces/guard.js";
+import { forgetReaderSpaceCredential, readerSpaceCredential, SpaceCredentialError, } from "./spaces/credential.js";
 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 { resolveRecords } from "./hydrate.js";
-import { getLexicon } from "./schema.js";
+import { log, emit, timer } from "./logger.js";
+import { runSQL, packCursor, unpackCursor, isTakendownDid, filterTakendownDids, searchRecords, findUriByFields, } from "./database/db.js";
+import { resolveRecords, buildBaseContext } from "./hydrate.js";
+import { getLexicon } from "./database/schema.js";
+import { createHmac } from 'node:crypto';
+import { pdsCreateRecord, pdsPutRecord, pdsDeleteRecord, pdsApplyWrites, pdsXrpc } from "./pds-proxy.js";
+import { obtainSession, ObtainSessionError } from "./oauth/server.js";
+let _oauthConfig = null;
+/** Set the OAuth config used for record write helpers. Called once during boot. */
+export function configureOAuth(config) {
+    _oauthConfig = config;
+}
+/** Thrown from XRPC handlers to return a 400 response with an error message. */
 export class InvalidRequestError extends Error {
     status = 400;
     errorName;
@@ -20,6 +51,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,21 +59,149 @@ export class NotFoundError extends InvalidRequestError {
     }
 }
 let _relayUrl = '';
+let _cdn = null;
+/** Set the relay URL used for blob URL generation. Called once during boot. */
+/** True when the relay is a loopback URL — a dev PDS rather than the network. */
+export function isLocalRelay() {
+    try {
+        const host = new URL(_relayUrl).hostname;
+        return (host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host === '::1' || host.endsWith('.localhost'));
+    }
+    catch {
+        return false;
+    }
+}
 export function configureRelay(relay) {
     _relayUrl = relay;
 }
+/** Set the CDN config for imgproxy URL signing. Called once during boot. */
+export function configureCdn(cdn) {
+    if (cdn) {
+        _cdn = {
+            url: cdn.url.replace(/\/$/, ''),
+            key: Buffer.from(cdn.key, 'hex'),
+            salt: Buffer.from(cdn.salt, 'hex'),
+        };
+    }
+    else {
+        _cdn = null;
+    }
+}
+/** Sign an imgproxy path with HMAC-SHA256 (URL-safe base64). */
+function signPath(path) {
+    const hmac = createHmac('sha256', _cdn.key);
+    hmac.update(_cdn.salt);
+    hmac.update(path);
+    const sig = hmac.digest('base64url');
+    return `/${sig}${path}`;
+}
+/**
+ * Generate a CDN URL for a blob ref. Uses the PDS directly in local dev,
+ * a configured imgproxy CDN if available, or the Bluesky CDN as fallback.
+ */
 export function blobUrl(did, ref, preset = 'avatar') {
     if (!ref)
         return undefined;
     const p = typeof ref === 'string' ? JSON.parse(ref) : ref;
     if (!p?.ref?.$link)
         return undefined;
-    if (_relayUrl.includes('localhost:2583')) {
-        return `http://localhost:2583/xrpc/com.atproto.sync.getBlob?did=${did}&cid=${p.ref.$link}`;
+    // A local network has no image CDN. Serve blobs through the dev proxy
+    // (see /blob/ in server.ts), which fetches from each repo's own PDS — on a
+    // multi-PDS dev stack the repos are not all behind the relay being tailed.
+    if (isLocalRelay()) {
+        return `/blob/${did}/${p.ref.$link}`;
+    }
+    if (_cdn) {
+        const path = `/${preset}/plain/${did}/${p.ref.$link}`;
+        return `${_cdn.url}${signPath(path)}`;
     }
     return `https://cdn.bsky.app/img/${preset}/plain/${did}/${p.ref.$link}@jpeg`;
 }
+/** Build a full XrpcContext from request parameters. Reuses buildBaseContext for shared fields. */
+export function buildXrpcContext(params, cursor, limit, viewer, input) {
+    const base = buildBaseContext(viewer);
+    return {
+        ...base,
+        db: { query: guardedQuerySQL, run: runSQL, unfiltered: unfilteredQuerySQL },
+        params,
+        input: input || {},
+        cursor,
+        limit,
+        packCursor,
+        unpackCursor,
+        isTakendown: isTakendownDid,
+        filterTakendownDids,
+        search: searchRecords,
+        resolve: resolveRecords,
+        exists: async (collection, filters) => {
+            const conditions = Object.entries(filters).map(([field, value]) => ({ field, value }));
+            const uri = await findUriByFields(collection, conditions);
+            return uri !== null;
+        },
+        ...accountHelpers(viewer),
+        spaceCredential: async (space, opts) => {
+            if (!_oauthConfig)
+                throw new Error('No OAuth config — cannot read a space');
+            if (!viewer)
+                throw new SpaceCredentialError(401, 'AuthRequired', 'Authentication required to read a space');
+            return readerSpaceCredential(_oauthConfig, viewer.did, space, opts);
+        },
+        forgetSpaceCredential: (space) => {
+            if (viewer)
+                forgetReaderSpaceCredential(viewer.did, space);
+        },
+        asAccount: (did) => accountHelpers({ did }),
+        obtainSession: async (url, body, opts) => {
+            if (!_oauthConfig)
+                throw new Error('No OAuth config — cannot obtain a session');
+            try {
+                return await obtainSession(_oauthConfig, url, body, opts);
+            }
+            catch (err) {
+                if (err instanceof ObtainSessionError)
+                    throw new InvalidRequestError(err.message, err.error);
+                throw err;
+            }
+        },
+    };
+}
+/**
+ * The PDS helpers for one account, with the session this app holds for it: the
+ * viewer's, or another account's through {@link XrpcContext.asAccount}.
+ */
+function accountHelpers(account) {
+    const ready = (what) => {
+        if (!_oauthConfig)
+            throw new Error(`No OAuth config — cannot ${what}`);
+        if (!account)
+            throw new Error(`Authentication required to ${what}`);
+        return { config: _oauthConfig, account };
+    };
+    return {
+        createRecord: async (collection, record, opts) => {
+            const { config, account } = ready('write records');
+            return pdsCreateRecord(config, account, { collection, record, rkey: opts?.rkey });
+        },
+        putRecord: async (collection, rkey, record) => {
+            const { config, account } = ready('write records');
+            return pdsPutRecord(config, account, { collection, rkey, record });
+        },
+        deleteRecord: async (collection, rkey) => {
+            const { config, account } = ready('write records');
+            await pdsDeleteRecord(config, account, { collection, rkey });
+        },
+        applyWrites: async (writes) => {
+            const { config, account } = ready('write records');
+            return pdsApplyWrites(config, account, { writes });
+        },
+        pds: async (nsid, options) => {
+            const { config, account } = ready('call the PDS');
+            return pdsXrpc(config, account, nsid, options);
+        },
+    };
+}
 const handlers = new Map();
+/** Recursively collect .ts/.js files in a directory, skipping files prefixed with `_`. */
 function walkDir(dir) {
     const results = [];
     try {
@@ -58,6 +218,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 +230,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);
@@ -75,65 +240,127 @@ export async function initXrpc(xrpcDir) {
         handlers.set(name, {
             name,
             execute: async (params, cursor, limit, viewer, input) => {
-                // Apply defaults and coerce types from lexicon
-                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,
-                };
+                coerceParams(params, paramProperties, requiredParams);
+                const ctx = buildXrpcContext(params, cursor, limit, viewer, input);
                 return handler.handler(ctx);
             },
         });
         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) => {
+            coerceParams(params, paramProperties, requiredParams);
+            const ctx = buildXrpcContext(params, cursor, limit, viewer, input);
+            return handlerModule.handler(ctx);
+        },
+    });
+}
+/** Collect a query string into params, keeping every value of a repeated key. */
+export function paramsFromSearch(search) {
+    const params = {};
+    for (const [key, value] of search) {
+        const prior = params[key];
+        if (prior === undefined)
+            params[key] = value;
+        else if (Array.isArray(prior))
+            prior.push(value);
+        else
+            params[key] = [prior, value];
+    }
+    return params;
+}
+function coerceScalar(value, def) {
+    // Only integers, as before: a boolean still reaches the handler as the
+    // string it was sent as, and handlers written against that keep working.
+    return def?.type === 'integer' ? Number(value) : value;
+}
+/**
+ * Apply the lexicon's parameter schema before a handler runs: defaults,
+ * integer coercion, and arrays. A query string cannot say whether
+ * `dids=x` is one string or a one-element list, so the schema decides: a
+ * parameter declared `array` always reaches the handler as one, or a handler
+ * that spreads it would spread the characters of a DID instead.
+ */
+export function coerceParams(params, properties, required) {
+    for (const [key, def] of Object.entries(properties)) {
+        if (params[key] == null && def.default != null) {
+            params[key] = def.type === 'array' ? [...def.default] : def.type === 'string' ? String(def.default) : def.default;
+        }
+        if (params[key] == null)
+            continue;
+        if (def.type === 'array') {
+            const list = Array.isArray(params[key]) ? params[key] : [params[key]];
+            params[key] = list.map((v) => coerceScalar(v, def.items));
+        }
+        else if (Array.isArray(params[key])) {
+            // A scalar given twice: the last one wins, as a form submission would.
+            params[key] = coerceScalar(params[key][params[key].length - 1], def);
+        }
+        else {
+            params[key] = coerceScalar(params[key], def);
+        }
+    }
+    for (const param of required) {
+        const v = params[param];
+        if (v == null || v === '' || (Array.isArray(v) && v.length === 0)) {
+            throw new InvalidRequestError(`Missing required parameter: ${param}`, 'InvalidRequest');
+        }
+    }
+}
+/** 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);
+    const elapsed = timer();
+    try {
+        const result = await handler.execute(params, cursor, limit, viewer || null, input);
+        emit('xrpc', name, { duration_ms: elapsed(), params, cursor, limit, viewer: viewer?.did });
+        return result;
+    }
+    catch (err) {
+        emit('xrpc', name, { duration_ms: elapsed(), params, cursor, limit, viewer: viewer?.did, error: err.message });
+        throw err;
+    }
+}
+/** 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)
+            continue;
+        // A list stays a list, as the query string would have carried it.
+        stringParams[k] = Array.isArray(v) ? v.map(String) : 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());
 }