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

package/dist/setup.d.ts

@@ -1,8 +1,35 @@
+import type { BulkInserter } from './database/ports.ts';
+/** Context passed to each setup script's handler function. */
 export interface SetupContext {
     db: {
         query: (sql: string, params?: any[]) => Promise<any[]>;
-        run: (sql: string, ...params: any[]) => Promise<void>;
+        run: (sql: string, params?: any[]) => Promise<void>;
+        runBatch: (operations: Array<{
+            sql: string;
+            params: any[];
+        }>) => Promise<void>;
+        createBulkInserter: (table: string, columns: string[], options?: {
+            onConflict?: 'ignore' | 'replace';
+            batchSize?: number;
+        }) => Promise<BulkInserter>;
     };
 }
+export type SetupHandler = (ctx: SetupContext) => Promise<void>;
+export declare function defineSetup(handler: SetupHandler): {
+    __type: "setup";
+    handler: SetupHandler;
+};
+/**
+ * Run all setup scripts in the given directory on server boot.
+ *
+ * Each script should export a default handler function (or `{ handler }`) that
+ * receives a {@link SetupContext} with database access. Scripts run in sorted
+ * filename order — prefix with numbers (e.g. `01-create-tables.ts`) to control
+ * execution order. Files starting with `_` are ignored.
+ *
+ * @param setupDir - Absolute path to the `setup/` directory
+ */
 export declare function initSetup(setupDir: string): Promise<void>;
+/** Run a single setup handler with a SetupContext. */
+export declare function runSetupHandler(name: string, handler: SetupHandler): Promise<void>;
 //# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE;QACF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;QACtD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KACtD,CAAA;CACF;AAiBD,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB/D"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE;QACF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;QACtD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QACnD,QAAQ,EAAE,CAAC,UAAU,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,GAAG,EAAE,CAAA;SAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QAC9E,kBAAkB,EAAE,CAClB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,CAAC,EAAE;YAAE,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;YAAC,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,KAChE,OAAO,CAAC,YAAY,CAAC,CAAA;KAC3B,CAAA;CACF;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE/D,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY;;;EAEhD;AAkBD;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB/D;AAED,sDAAsD;AACtD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxF"}

package/dist/setup.js

@@ -6,10 +6,38 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+/**
+ * Setup scripts that run once on server boot for initializing custom tables,
+ * views, or other database state.
+ *
+ * Place scripts in the `setup/` directory. Each module default-exports a handler
+ * function (or `{ handler }`) that receives a {@link SetupContext} with database
+ * access. Scripts run in sorted filename order — prefix with numbers to control
+ * execution order. Files starting with `_` are ignored.
+ *
+ * @example
+ * ```ts
+ * // setup/01-leaderboard.ts
+ * import type { SetupContext } from '@hatk/hatk/setup'
+ *
+ * export default async function (ctx: SetupContext) {
+ *   await ctx.db.run(`
+ *     CREATE TABLE IF NOT EXISTS leaderboard (
+ *       did TEXT PRIMARY KEY,
+ *       score INTEGER DEFAULT 0
+ *     )
+ *   `)
+ * }
+ * ```
+ */
 import { resolve, relative } from 'node:path';
 import { readdirSync, statSync } from 'node:fs';
 import { log } from "./logger.js";
-import { querySQL, runSQL } from "./db.js";
+import { querySQL, runSQL, runBatch, createBulkInserterSQL } from "./database/db.js";
+export function defineSetup(handler) {
+    return { __type: 'setup', handler };
+}
+/** Recursively collect .ts/.js files in a directory, skipping files prefixed with `_`. */
 function walkDir(dir) {
     const results = [];
     try {
@@ -26,23 +54,42 @@ function walkDir(dir) {
     catch { }
     return results.sort();
 }
+/**
+ * Run all setup scripts in the given directory on server boot.
+ *
+ * Each script should export a default handler function (or `{ handler }`) that
+ * receives a {@link SetupContext} with database access. Scripts run in sorted
+ * filename order — prefix with numbers (e.g. `01-create-tables.ts`) to control
+ * execution order. Files starting with `_` are ignored.
+ *
+ * @param setupDir - Absolute path to the `setup/` directory
+ */
 export async function initSetup(setupDir) {
     const files = walkDir(setupDir);
     if (files.length === 0)
         return;
     for (const scriptPath of files) {
         const name = relative(setupDir, scriptPath).replace(/\.(ts|js)$/, '');
-        const mod = await import(__rewriteRelativeImportExtension(scriptPath));
+        const mod = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ `${scriptPath}?t=${Date.now()}`));
         const handler = mod.default?.handler || mod.default;
         if (typeof handler !== 'function') {
             console.warn(`[setup] ${name}: no handler function found, skipping`);
             continue;
         }
         const ctx = {
-            db: { query: querySQL, run: runSQL },
+            db: { query: querySQL, run: runSQL, runBatch, createBulkInserter: createBulkInserterSQL },
         };
         log(`[setup] running: ${name}`);
         await handler(ctx);
         log(`[setup] done: ${name}`);
     }
 }
+/** Run a single setup handler with a SetupContext. */
+export async function runSetupHandler(name, handler) {
+    const ctx = {
+        db: { query: querySQL, run: runSQL, runBatch, createBulkInserter: createBulkInserterSQL },
+    };
+    log(`[setup] running: ${name}`);
+    await handler(ctx);
+    log(`[setup] done: ${name}`);
+}

package/dist/spaces/blob.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Serving a blob that lives in a permissioned space.
+ *
+ * Every other image hatk hands out has a public URL — a CDN path, or the
+ * repo's own `com.atproto.sync.getBlob`. A space's blob has neither, by
+ * design: `com.atproto.space.getBlob` serves it only to a credential holder,
+ * and only for a space the blob is actually referenced from. Giving one a
+ * public URL would turn that URL into the capability the credential exists to
+ * replace.
+ *
+ * So the bytes come through here, and every request is authorized before any
+ * of them move: the viewer's credential for the space, or the same 404 a
+ * missing blob gets. What that authorization guards is served two ways —
+ * `private` so the viewer's own browser may hold it and no shared cache may,
+ * and out of a bounded in-memory cache so the same photo is fetched from its
+ * repo once rather than once per member looking at it.
+ */
+import type { OAuthConfig } from '../config.ts';
+/**
+ * The sizes a space blob is served at.
+ *
+ * The same words hatk's public path uses for imgproxy, with the same numbers,
+ * so an app naming a size says it once and means it either side of the line
+ * between a public blob and a permissioned one. What differs is who resizes:
+ * a space blob may not pass through an image CDN, so it happens here.
+ *
+ * A request naming none gets the original, which is what every caller written
+ * before presets existed asks for.
+ */
+declare const PRESETS: {
+    readonly avatar: {
+        readonly width: 1000;
+        readonly height: 1000;
+        readonly fit: "cover";
+        readonly quality: 85;
+    };
+    readonly avatar_thumbnail: {
+        readonly width: 128;
+        readonly height: 128;
+        readonly fit: "cover";
+        readonly quality: 70;
+    };
+    readonly feed_thumbnail: {
+        readonly width: 1000;
+        readonly fit: "inside";
+        readonly quality: 70;
+    };
+    readonly feed_fullsize: {
+        readonly quality: 90;
+    };
+    readonly banner: {
+        readonly width: 3000;
+        readonly height: 1000;
+        readonly fit: "cover";
+        readonly quality: 85;
+    };
+};
+export type SpaceBlobPreset = keyof typeof PRESETS;
+/**
+ * Only a name from that list is a preset.
+ *
+ * Free-form dimensions would let anyone mint unlimited distinct cache keys and
+ * evict everything real, and would put the cost of an arbitrary resize behind
+ * a URL. An unrecognised name is treated as none rather than refused: a broken
+ * image is a worse answer than a large one.
+ */
+export declare function asPreset(name: string | null | undefined): SpaceBlobPreset | undefined;
+/**
+ * The URL this appview serves a space blob at, for whoever is asking.
+ *
+ * Built here rather than by the app, because the route is hatk's: a blob in a
+ * space has no public address by design, and this is the one address it does
+ * have — answered only to a viewer who may read the space it names.
+ */
+export declare function spaceBlobUrl(space: string, repo: string, cid: string, preset?: SpaceBlobPreset): string;
+/**
+ * The CID a blob reference names, in whichever spelling the read used.
+ *
+ * A repo read gives the lexicon's `{ ref: { $link } }`; a space read comes
+ * back through a lex client that decodes the same field into a CID object
+ * whose `/` is the string. One blob, two spellings, and no caller should have
+ * to know which it got.
+ */
+export declare function blobCid(blob: unknown): string | undefined;
+export interface SpaceBlobRequest {
+    space: string;
+    /** The repo holding the blob — the writer's, not the authority's. */
+    repo: string;
+    cid: string;
+    /** The size to serve it at. Absent means the original. */
+    preset?: SpaceBlobPreset;
+}
+export declare function parseSpaceBlobRequest(params: URLSearchParams): SpaceBlobRequest | null;
+/** Drop everything held. For tests, and for an operator who wants it gone. */
+export declare function resetSpaceBlobCache(): void;
+/**
+ * Fetch a space blob as this viewer, or answer why not.
+ *
+ * A viewer who cannot read the space gets the same 404 as a blob that is not
+ * there. The distinction between "you may not" and "it does not exist" is
+ * itself information about a private space, and the space host draws the line
+ * the same way when it reports a non-member's repo as simply absent.
+ *
+ * The credential is checked on every request, including the ones answered from
+ * the cache and the ones answered with a 304. Nothing here is ever served to
+ * somebody the authority has not just said yes to.
+ */
+export declare function serveSpaceBlob(oauth: OAuthConfig | null, viewer: {
+    did: string;
+} | null, request: SpaceBlobRequest, ifNoneMatch?: string | null): Promise<Response>;
+export {};
+//# sourceMappingURL=blob.d.ts.map

package/dist/spaces/blob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob.d.ts","sourceRoot":"","sources":["../../src/spaces/blob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AA6C/C;;;;;;;;;;GAUG;AACH,QAAA,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;CAMsG,CAAA;AAEnH,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,OAAO,CAAA;AAElD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAErF;AAKD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,CAIvG;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAMzD;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,0DAA0D;IAC1D,MAAM,CAAC,EAAE,eAAe,CAAA;CACzB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,CAQtF;AA0DD,8EAA8E;AAC9E,wBAAgB,mBAAmB,IAAI,IAAI,CAI1C;AAuDD;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,WAAW,GAAG,IAAI,EACzB,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC9B,OAAO,EAAE,gBAAgB,EACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,OAAO,CAAC,QAAQ,CAAC,CA+BnB"}