@hatk/hatk 0.0.1-alpha.9 → 0.0.1-alpha.90

package/dist/feeds.js

@@ -9,8 +9,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { resolve } from 'node:path';
 import { readdirSync } from 'node:fs';
 import { log } from "./logger.js";
-import { querySQL, packCursor, unpackCursor, isTakendownDid, filterTakendownDids } from "./db.js";
-import { resolveRecords, buildHydrateContext } from "./hydrate.js";
+import { packCursor, unpackCursor, isTakendownDid, filterTakendownDids, resolveHandleToDid, } from "./database/db.js";
+import { resolveRecords, buildBaseContext } from "./hydrate.js";
+import { spaceFilterSql } from "./spaces/visibility.js";
+import { guardedQuerySQL, unfilteredQuerySQL } from "./spaces/guard.js";
 export function createPaginate(deps) {
     return async (sql, opts) => {
         const { db, cursor, limit, packCursor: pack, unpackCursor: unpack } = deps;
@@ -25,6 +27,16 @@ export function createPaginate(deps) {
         const op = order === 'ASC' ? '>' : '<';
         let paramIdx = userParams.length + 1;
         const sqlParams = [...userParams];
+        // The permissioned-space gate, applied to whatever table the ordering
+        // names — the same table `cid` is read from. Feed SQL is hand-written and
+        // nothing can inject a predicate into a string somebody else wrote, so
+        // building it here is the only way every feed gets it without every feed
+        // author remembering to. Outside a viewer's scope it is `space IS NULL`
+        // and binds nothing, which is what it compiles to on an instance that
+        // indexes no space.
+        const gate = spaceFilterSql(prefix.replace(/\.$/, ''), paramIdx);
+        sqlParams.push(...gate.params);
+        paramIdx = gate.nextIdx;
         // Build cursor condition
         let cursorCondition = '';
         if (cursor) {
@@ -35,15 +47,12 @@ export function createPaginate(deps) {
                 paramIdx += 3;
             }
         }
-        // Detect existing WHERE and append cursor condition
+        // Detect existing WHERE and append the gate and the cursor condition
         let fullSql = sql;
-        if (cursorCondition) {
-            if (/\bWHERE\b/i.test(sql)) {
-                fullSql += ` AND ${cursorCondition}`;
-            }
-            else {
-                fullSql += ` WHERE ${cursorCondition}`;
-            }
+        const appended = [gate.sql, ...(cursorCondition ? [cursorCondition] : [])];
+        if (appended.length) {
+            const joiner = /\bWHERE\b/i.test(sql) ? 'AND' : 'WHERE';
+            fullSql += ` ${joiner} ${appended.join(' AND ')}`;
         }
         fullSql += ` ORDER BY ${orderBy} ${order}, ${cidCol} ${order} LIMIT $${paramIdx}`;
         sqlParams.push(limit + 1);
@@ -59,7 +68,47 @@ export function createPaginate(deps) {
     };
 }
 export function defineFeed(opts) {
-    return { ...opts, generate: (ctx) => opts.generate({ ...ctx, ok: (v) => v }) };
+    return { __type: 'feed', ...opts, generate: (ctx) => opts.generate({ ...ctx, ok: (v) => v }) };
+}
+/** Register a single feed from a scanned server/ module. */
+export function registerFeed(name, generator) {
+    const handler = {
+        name,
+        label: generator.label || name,
+        collection: generator.collection,
+        view: generator.view,
+        generate: async (params, cursor, limit, viewer) => {
+            const paginateDeps = {
+                db: { query: guardedQuerySQL, unfiltered: unfilteredQuerySQL },
+                cursor,
+                limit,
+                packCursor,
+                unpackCursor,
+            };
+            const ctx = {
+                db: { query: guardedQuerySQL, unfiltered: unfilteredQuerySQL },
+                params,
+                cursor,
+                limit,
+                viewer,
+                packCursor,
+                unpackCursor,
+                isTakendown: isTakendownDid,
+                filterTakendownDids,
+                paginate: createPaginate(paginateDeps),
+                spaceFilter: spaceFilterSql,
+            };
+            const result = await generator.generate(ctx);
+            if (Array.isArray(result)) {
+                return { uris: result.map((r) => r.uri || r) };
+            }
+            return { uris: result.uris, cursor: result.cursor };
+        },
+    };
+    if (typeof generator.hydrate === 'function') {
+        handler.hydrate = generator.hydrate;
+    }
+    feeds.set(name, handler);
 }
 const feeds = new Map();
 export async function initFeeds(feedsDir) {
@@ -75,7 +124,7 @@ export async function initFeeds(feedsDir) {
     for (const file of files) {
         const name = file.replace(/\.(ts|js)$/, '');
         const scriptPath = resolve(feedsDir, file);
-        const mod = await import(__rewriteRelativeImportExtension(scriptPath));
+        const mod = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ `${scriptPath}?t=${Date.now()}`));
         const generator = mod.default;
         const handler = {
             name,
@@ -84,14 +133,14 @@ export async function initFeeds(feedsDir) {
             view: generator.view,
             generate: async (params, cursor, limit, viewer) => {
                 const paginateDeps = {
-                    db: { query: querySQL },
+                    db: { query: guardedQuerySQL, unfiltered: unfilteredQuerySQL },
                     cursor,
                     limit,
                     packCursor,
                     unpackCursor,
                 };
                 const ctx = {
-                    db: { query: querySQL },
+                    db: { query: guardedQuerySQL, unfiltered: unfilteredQuerySQL },
                     params,
                     cursor,
                     limit,
@@ -101,6 +150,7 @@ export async function initFeeds(feedsDir) {
                     isTakendown: isTakendownDid,
                     filterTakendownDids,
                     paginate: createPaginate(paginateDeps),
+                    spaceFilter: spaceFilterSql,
                 };
                 const result = await generator.generate(ctx);
                 if (Array.isArray(result)) {
@@ -127,11 +177,17 @@ export async function executeFeed(name, params, cursor, limit, viewer) {
     const handler = feeds.get(name);
     if (!handler)
         return null;
+    // Resolve handle-based actor param to DID
+    if (params.actor && !params.actor.startsWith('did:')) {
+        const resolved = await resolveHandleToDid(params.actor);
+        if (resolved)
+            params.actor = resolved;
+    }
     const result = await handler.generate(params, cursor, limit, viewer || null);
     if (handler.hydrate) {
         const items = await resolveRecords(result.uris);
-        const ctx = buildHydrateContext(items, viewer || null);
-        const hydrated = await handler.hydrate(ctx);
+        const ctx = buildBaseContext(viewer || null);
+        const hydrated = await handler.hydrate(ctx, items);
         return { items: hydrated, cursor: result.cursor };
     }
     return { uris: result.uris, cursor: result.cursor };

package/dist/hooks.d.ts

@@ -0,0 +1,102 @@
+import type { OAuthConfig } from './config.ts';
+import { type BaseContext } from './hydrate.ts';
+import { type PushInterface } from './push.ts';
+/** Context passed to the on-login hook after a successful OAuth login. */
+export type OnLoginCtx = Omit<BaseContext, 'db'> & {
+    /** DID of the user who just logged in. */
+    did: string;
+    /** Database access with both read and write. */
+    db: {
+        query: (sql: string, params?: unknown[]) => Promise<unknown[]>;
+        run: (sql: string, params?: unknown[]) => Promise<void>;
+        /**
+         * Raw SQL with the permissioned-space guard off. A hook is not serving a
+         * viewer, and discovering what a space contains — which spaces a
+         * community lists, say — is exactly a read over space rows that no scope
+         * is open for. See `spaces/guard.ts`.
+         */
+        unfiltered: (sql: string, params?: unknown[]) => Promise<unknown[]>;
+    };
+    /** Trigger a backfill for a DID and wait for it to complete. */
+    ensureRepo: (did: string) => Promise<void>;
+    /** Write a record to the user's PDS and index locally. */
+    createRecord: (collection: string, record: Record<string, unknown>, opts?: {
+        rkey?: string;
+    }) => Promise<{
+        uri?: string;
+        cid?: string;
+    }>;
+    /** Create or update a record on the user's PDS and index locally. */
+    putRecord: (collection: string, rkey: string, record: Record<string, unknown>) => Promise<{
+        uri?: string;
+        cid?: string;
+    }>;
+    /** Delete a record from the user's PDS and local index. */
+    deleteRecord: (collection: string, rkey: string) => Promise<void>;
+};
+/** Context passed to on-commit hooks after a record is indexed. */
+export type OnCommitCtx = {
+    /** Whether the record was created or deleted. */
+    action: 'create' | 'delete';
+    /** The collection NSID that matched. */
+    collection: string;
+    /** The record value (null for deletes). */
+    record: Record<string, any> | null;
+    /** DID of the committing actor. */
+    repo: string;
+    /** AT URI of the record. */
+    uri: string;
+    /** Database access (read and write). */
+    db: {
+        query: (sql: string, params?: unknown[]) => Promise<unknown[]>;
+        run: (sql: string, params?: unknown[]) => Promise<void>;
+        /** Raw SQL with the permissioned-space guard off. See `spaces/guard.ts`. */
+        unfiltered: (sql: string, params?: unknown[]) => Promise<unknown[]>;
+    };
+    /** Typed record lookup (same as BaseContext). */
+    lookup: BaseContext['lookup'];
+    /** Push notification delivery. */
+    push: PushInterface;
+};
+export declare function defineHook(event: 'on-login', handler: (ctx: OnLoginCtx) => Promise<void>): {
+    __type: 'hook';
+    event: 'on-login';
+    handler: (ctx: OnLoginCtx) => Promise<void>;
+};
+export declare function defineHook(event: 'on-commit', options: {
+    collections: string[];
+}, handler: (ctx: OnCommitCtx) => Promise<void>): {
+    __type: 'hook';
+    event: 'on-commit';
+    collections: string[];
+    handler: (ctx: OnCommitCtx) => Promise<void>;
+};
+/**
+ * Discover and load the on-login hook from the project's `hooks/` directory.
+ * Looks for `on-login.ts` or `on-login.js`. Safe to call if no hook exists.
+ *
+ * The documented contract is `export default defineHook('on-login', handler)`,
+ * which is an object carrying the handler — the same shape the `server/`
+ * scanner recognizes by its `__type` tag. A bare async function is still
+ * accepted, because that is what the legacy `hooks/` directory used before
+ * `defineHook` existed. Anything else is reported rather than installed: a
+ * non-callable hook would otherwise fail silently on every login, since
+ * `fireOnLoginHook` swallows what the hook throws.
+ */
+export declare function loadOnLoginHook(hooksDir: string): Promise<void>;
+/** Register a hook from a scanned server/ module. */
+export declare function registerHook(event: string, handler: Function, options?: any): void;
+/** Fire the on-login hook if loaded. Errors are logged but never block login. */
+export declare function fireOnLoginHook(did: string, oauthConfig: OAuthConfig | null): Promise<void>;
+/**
+ * Fire on-commit hooks for a batch of indexed records.
+ * Runs async and non-blocking — errors are logged but never throw.
+ */
+export declare function fireOnCommitHooks(items: Array<{
+    action: 'create' | 'delete';
+    collection: string;
+    uri: string;
+    authorDid: string;
+    record: Record<string, any> | null;
+}>): void;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAK9C,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AACjE,OAAO,EAAqC,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA;AAEjF,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG;IACjD,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAA;IACX,gDAAgD;IAChD,EAAE,EAAE;QACF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;QAC9D,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QACvD;;;;;WAKG;QACH,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;KACpE,CAAA;IACD,gEAAgE;IAChE,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1C,0DAA0D;IAC1D,YAAY,EAAE,CACZ,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KACrB,OAAO,CAAC;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC5C,qEAAqE;IACrE,SAAS,EAAE,CACT,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC5C,2DAA2D;IAC3D,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAClE,CAAA;AAED,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG;IACxB,iDAAiD;IACjD,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC3B,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAA;IAClB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;IAClC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,wCAAwC;IACxC,EAAE,EAAE;QACF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;QAC9D,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QACvD,4EAA4E;QAC5E,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;KACpE,CAAA;IACD,iDAAiD;IACjD,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAA;IAC7B,kCAAkC;IAClC,IAAI,EAAE,aAAa,CAAA;CACpB,CAAA;AAQD,wBAAgB,UAAU,CACxB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAC1C;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAA;AACrF,wBAAgB,UAAU,CACxB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE;IAAE,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,EAClC,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAC3C;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAA;AAkB9G;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBrE;AAgBD,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI,CASlF;AAED,iFAAiF;AACjF,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BjG;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,KAAK,CAAC;IACX,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;CACnC,CAAC,GACD,IAAI,CA6BN"}

package/dist/hooks.js

@@ -0,0 +1,186 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Lifecycle hooks that run in response to server events.
+ *
+ * Place hook modules in the `hooks/` directory. Currently supported hooks:
+ *
+ * - `on-login.ts` — called after each successful OAuth login
+ * - `on-commit-*.ts` — called after records are indexed from the firehose
+ *
+ * Each hook default-exports the result of `defineHook()`.
+ *
+ * @example
+ * ```ts
+ * // hooks/on-login.ts
+ * import { defineHook } from '$hatk'
+ *
+ * export default defineHook("on-login", async (ctx) => {
+ *   await ctx.ensureRepo(ctx.did)
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // hooks/on-commit-favorite.ts
+ * import { defineHook } from '$hatk'
+ *
+ * export default defineHook("on-commit", { collections: ["social.grain.favorite"] },
+ *   async ({ action, collection, record, repo, uri, db, lookup, push }) => {
+ *     if (action !== "create") return
+ *     // send push notification, etc.
+ *   }
+ * )
+ * ```
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pdsCreateRecord, pdsPutRecord, pdsDeleteRecord } from "./pds-proxy.js";
+import { log, emit } from "./logger.js";
+import { setRepoStatus, runSQL } from "./database/db.js";
+import { triggerAutoBackfill, awaitBackfill } from "./indexer.js";
+import { buildBaseContext } from "./hydrate.js";
+import { buildPushInterface, isPushEnabled } from "./push.js";
+export function defineHook(event, ...args) {
+    if (event === 'on-login') {
+        return { __type: 'hook', event, handler: args[0] };
+    }
+    if (event === 'on-commit') {
+        const options = args[0];
+        const handler = args[1];
+        return { __type: 'hook', event, collections: options.collections, handler };
+    }
+    throw new Error(`Unknown hook event: ${event}`);
+}
+let onLoginHook = null;
+const onCommitHooks = [];
+/**
+ * Discover and load the on-login hook from the project's `hooks/` directory.
+ * Looks for `on-login.ts` or `on-login.js`. Safe to call if no hook exists.
+ *
+ * The documented contract is `export default defineHook('on-login', handler)`,
+ * which is an object carrying the handler — the same shape the `server/`
+ * scanner recognizes by its `__type` tag. A bare async function is still
+ * accepted, because that is what the legacy `hooks/` directory used before
+ * `defineHook` existed. Anything else is reported rather than installed: a
+ * non-callable hook would otherwise fail silently on every login, since
+ * `fireOnLoginHook` swallows what the hook throws.
+ */
+export async function loadOnLoginHook(hooksDir) {
+    const tsPath = resolve(hooksDir, 'on-login.ts');
+    const jsPath = resolve(hooksDir, 'on-login.js');
+    const path = existsSync(tsPath) ? tsPath : existsSync(jsPath) ? jsPath : null;
+    if (!path)
+        return;
+    const mod = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ `${path}?t=${Date.now()}`));
+    const handler = resolveHookHandler(mod.default);
+    if (!handler) {
+        emit('hooks', 'on_login_load_error', {
+            path,
+            error: 'default export is not a function or a defineHook("on-login", ...) result',
+        });
+        return;
+    }
+    onLoginHook = handler;
+    log('[hooks] on-login hook loaded');
+}
+/** Unwrap a hook module's default export into the callable handler, if it has one. */
+function resolveHookHandler(exported) {
+    if (typeof exported === 'function')
+        return exported;
+    const handler = exported?.handler;
+    return typeof handler === 'function' ? handler : null;
+}
+/** Mark a DID as pending, trigger auto-backfill, and wait for completion. */
+async function ensureRepo(did) {
+    await setRepoStatus(did, 'pending');
+    triggerAutoBackfill(did);
+    await awaitBackfill(did);
+}
+/** Register a hook from a scanned server/ module. */
+export function registerHook(event, handler, options) {
+    if (event === 'on-login') {
+        onLoginHook = handler;
+        log('[hooks] on-login hook registered');
+    }
+    else if (event === 'on-commit') {
+        const collections = new Set(options?.collections || []);
+        onCommitHooks.push({ collections, handler: handler });
+        log(`[hooks] on-commit hook registered (collections: ${[...collections].join(', ')})`);
+    }
+}
+/** Fire the on-login hook if loaded. Errors are logged but never block login. */
+export async function fireOnLoginHook(did, oauthConfig) {
+    if (!onLoginHook)
+        return;
+    try {
+        const base = buildBaseContext({ did });
+        const viewer = { did };
+        const hookPromise = onLoginHook({
+            ...base,
+            did,
+            db: { query: base.db.query, run: runSQL, unfiltered: base.db.unfiltered },
+            ensureRepo,
+            createRecord: async (collection, record, opts) => {
+                if (!oauthConfig)
+                    throw new Error('No OAuth config — cannot write to PDS');
+                return pdsCreateRecord(oauthConfig, viewer, { collection, record, rkey: opts?.rkey });
+            },
+            putRecord: async (collection, rkey, record) => {
+                if (!oauthConfig)
+                    throw new Error('No OAuth config — cannot write to PDS');
+                return pdsPutRecord(oauthConfig, viewer, { collection, rkey, record });
+            },
+            deleteRecord: async (collection, rkey) => {
+                if (!oauthConfig)
+                    throw new Error('No OAuth config — cannot write to PDS');
+                await pdsDeleteRecord(oauthConfig, viewer, { collection, rkey });
+            },
+        });
+        const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('on-login hook timed out after 30s')), 30_000));
+        await Promise.race([hookPromise, timeout]);
+    }
+    catch (err) {
+        emit('hooks', 'on_login_error', { did, error: err.message });
+    }
+}
+/**
+ * Fire on-commit hooks for a batch of indexed records.
+ * Runs async and non-blocking — errors are logged but never throw.
+ */
+export function fireOnCommitHooks(items) {
+    if (onCommitHooks.length === 0)
+        return;
+    const base = buildBaseContext(null);
+    const push = isPushEnabled() ? buildPushInterface() : { send: async () => { } };
+    for (const item of items) {
+        for (const hook of onCommitHooks) {
+            if (hook.collections.size > 0 && !hook.collections.has(item.collection))
+                continue;
+            hook
+                .handler({
+                action: item.action,
+                collection: item.collection,
+                record: item.record,
+                repo: item.authorDid,
+                uri: item.uri,
+                db: { query: base.db.query, run: runSQL, unfiltered: base.db.unfiltered },
+                lookup: base.lookup,
+                push,
+            })
+                .catch((err) => {
+                emit('hooks', 'on_commit_error', {
+                    collection: item.collection,
+                    uri: item.uri,
+                    error: err.message,
+                });
+            });
+        }
+    }
+}

package/dist/hydrate.d.ts

@@ -1,23 +1,66 @@
 import type { Row } from './lex-types.ts';
 export type { Row };
-export interface HydrateContext<T = unknown> {
-    items: Row<T>[];
+export interface BaseContext {
     viewer: {
         did: string;
+        handle?: string;
     } | null;
     db: {
         query: (sql: string, params?: unknown[]) => Promise<unknown[]>;
+        /**
+         * Raw SQL with the permissioned-space guard off. Named so it can be found
+         * with grep: for results never served to a viewer, such as an admin
+         * rollup. See `spaces/guard.ts`.
+         */
+        unfiltered: (sql: string, params?: unknown[]) => Promise<unknown[]>;
     };
     getRecords: <R = unknown>(collection: string, uris: string[]) => Promise<Map<string, Row<R>>>;
     lookup: <R = unknown>(collection: string, field: string, values: string[]) => Promise<Map<string, Row<R>>>;
     count: (collection: string, field: string, values: string[]) => Promise<Map<string, number>>;
     labels: (uris: string[]) => Promise<Map<string, unknown[]>>;
-    blobUrl: (did: string, ref: unknown, preset?: 'avatar' | 'banner' | 'feed_thumbnail' | 'feed_fullsize') => string | undefined;
+    blobUrl: (did: string, ref: unknown, preset?: string) => string | undefined;
+    /**
+     * The permissioned-space gate, for hand-written SQL.
+     *
+     * Every helper on this context applies it already. Raw SQL through
+     * `ctx.db.query` cannot — nothing can inject a predicate into a string
+     * somebody else wrote — so a query that selects from a collection a space
+     * writes into has to apply it itself:
+     *
+     * ```ts
+     * const gate = ctx.spaceFilter('t', 2)
+     * ctx.db.query(
+     *   `SELECT t.* FROM "app.example.post" t WHERE t.did = $1 AND ${gate.sql}`,
+     *   ['did:plc:someone', ...gate.params],
+     * )
+     * ```
+     *
+     * Outside a viewer's scope this is `t.space IS NULL` and binds nothing, so on
+     * an instance that indexes no space it costs one predicate on an indexed
+     * column and changes no result.
+     */
+    spaceFilter: (alias: string, startIdx: number) => {
+        sql: string;
+        params: string[];
+        nextIdx: number;
+    };
+    /**
+     * Every record of a collection in a space the viewer may read. Empty for a
+     * space outside their scope; see `requireSpace` for the explicit refusal.
+     */
+    spaceRecords: <R = unknown>(collection: string, space: string) => Promise<Row<R>[]>;
+    /** Every record where `field` is one of `values` — the many-rows counterpart of `lookup`. */
+    records: <R = unknown>(collection: string, field: string, values: string[]) => Promise<Row<R>[]>;
+    /** Throw `NotAuthorized` unless the viewer may read this space. */
+    requireSpace: (space: string) => void;
+    /** The URL this appview serves a space blob at, for the viewer asking. */
+    spaceBlobUrl: (space: string, repo: string, cid: string) => string;
 }
 /** Fetch records for URIs, reshape them, and filter out taken-down DIDs. */
 export declare function resolveRecords(uris: string[]): Promise<Row<unknown>[]>;
-/** Build a HydrateContext for a feed's hydrate function. */
-export declare function buildHydrateContext(items: Row<unknown>[], viewer: {
+/** Build a BaseContext for hydration. */
+export declare function buildBaseContext(viewer: {
     did: string;
-} | null): HydrateContext;
+    handle?: string;
+} | null): BaseContext;
 //# sourceMappingURL=hydrate.d.ts.map

package/dist/hydrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AAEzC,YAAY,EAAE,GAAG,EAAE,CAAA;AAInB,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IACf,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAC9B,EAAE,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;KAAE,CAAA;IACtE,UAAU,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7F,MAAM,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1G,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC5F,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA;IAC3D,OAAO,EAAE,CACP,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,OAAO,EACZ,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,gBAAgB,GAAG,eAAe,KAC9D,MAAM,GAAG,SAAS,CAAA;CACxB;AAID,4EAA4E;AAC5E,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAoC5E;AAID,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,cAAc,CA4BzG"}
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AAEzC,YAAY,EAAE,GAAG,EAAE,CAAA;AAInB,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAC/C,EAAE,EAAE;QACF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;QAC9D;;;;WAIG;QACH,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;KACpE,CAAA;IACD,UAAU,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7F,MAAM,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1G,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC5F,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA;IAC3D,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;IAC3E;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IACpG;;;OAGG;IACH,YAAY,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACnF,6FAA6F;IAC7F,OAAO,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAChG,mEAAmE;IACnE,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACrC,0EAA0E;IAC1E,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAA;CACnE;AAID,4EAA4E;AAC5E,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAsC5E;AAID,yCAAyC;AACzC,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,WAAW,CAuB7F"}

package/dist/hydrate.js

@@ -1,15 +1,23 @@
-import { getRecordsByUris, countByFieldBatch, lookupByFieldBatch, querySQL, reshapeRow, queryLabelsForUris, filterTakendownDids, } from "./db.js";
+import { getRecordsMap, countByFieldBatch, lookupByFieldBatch, queryLabelsForUris, filterTakendownDids, getRecordsByUris, reshapeRow, } from "./database/db.js";
 import { blobUrl } from "./xrpc.js";
+import { collectionFromRecordUri } from "./spaces/uri.js";
+import { spaceFilterSql } from "./spaces/visibility.js";
+import { guardedQuerySQL, unfilteredQuerySQL } from "./spaces/guard.js";
+import { records, requireSpace, spaceRecords } from "./spaces/records.js";
+import { spaceBlobUrl } from "./spaces/blob.js";
 // --- Record Resolution ---
 /** Fetch records for URIs, reshape them, and filter out taken-down DIDs. */
 export async function resolveRecords(uris) {
     if (uris.length === 0)
         return [];
-    // Group URIs by collection for batch fetching
+    // Group URIs by collection for batch fetching. A space record's collection
+    // sits in a different segment than a repo record's, so the position is read
+    // by a parser that knows both shapes rather than inline.
     const byCollection = new Map();
     for (const uri of uris) {
-        const parts = uri.replace('at://', '').split('/');
-        const col = parts[1];
+        const col = collectionFromRecordUri(uri);
+        if (!col)
+            continue;
         if (!byCollection.has(col))
             byCollection.set(col, []);
         byCollection.get(col).push(uri);
@@ -39,24 +47,12 @@ export async function resolveRecords(uris) {
         .filter((r) => r != null);
 }
 // --- Context Builder ---
-/** Build a HydrateContext for a feed's hydrate function. */
-export function buildHydrateContext(items, viewer) {
+/** Build a BaseContext for hydration. */
+export function buildBaseContext(viewer) {
     return {
-        items,
         viewer,
-        db: { query: querySQL },
-        getRecords: async (collection, uris) => {
-            if (uris.length === 0)
-                return new Map();
-            const records = await getRecordsByUris(collection, uris);
-            const map = new Map();
-            for (const r of records) {
-                const shaped = reshapeRow(r, r?.__childData, r?.__unionData);
-                if (shaped)
-                    map.set(shaped.uri, shaped);
-            }
-            return map;
-        },
+        db: { query: guardedQuerySQL, unfiltered: unfilteredQuerySQL },
+        getRecords: getRecordsMap,
         lookup: async (collection, field, values) => {
             if (values.length === 0)
                 return new Map();
@@ -71,5 +67,10 @@ export function buildHydrateContext(items, viewer) {
         },
         labels: queryLabelsForUris,
         blobUrl,
+        spaceFilter: spaceFilterSql,
+        spaceRecords,
+        records,
+        requireSpace,
+        spaceBlobUrl,
     };
 }