@absurd-sqlite/sdk 0.2.1-alpha.0 → 0.2.1-alpha.2

package/dist/cjs/extension-downloader.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadExtension = downloadExtension;
+exports.resolveExtensionPath = resolveExtensionPath;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const node_crypto_1 = require("node:crypto");
+function getPlatformInfo() {
+    const platform = process.platform;
+    const arch = process.arch;
+    let os;
+    let ext;
+    switch (platform) {
+        case "darwin":
+            os = "macOS";
+            ext = "dylib";
+            break;
+        case "linux":
+            os = "Linux";
+            ext = "so";
+            break;
+        case "win32":
+            os = "Windows";
+            ext = "dll";
+            break;
+        default:
+            throw new Error(`Unsupported platform: ${platform}`);
+    }
+    let archStr;
+    switch (arch) {
+        case "x64":
+            archStr = "X64";
+            break;
+        case "arm64":
+            archStr = "ARM64";
+            break;
+        default:
+            throw new Error(`Unsupported architecture: ${arch}`);
+    }
+    return { os, arch: archStr, ext };
+}
+function getDefaultCacheDir() {
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), ".cache", "absurd-sqlite", "extensions");
+}
+function getAssetName(version, platform) {
+    // Format: absurd-absurd-sqlite-extension-vX.Y.Z-{OS}-{ARCH}.{ext}
+    return `absurd-absurd-sqlite-extension-${version}-${platform.os}-${platform.arch}.${platform.ext}`;
+}
+function getTag(version) {
+    return `absurd-sqlite-extension/${version}`;
+}
+async function fetchLatestVersion(owner, repo) {
+    const url = `https://api.github.com/repos/${owner}/${repo}/releases`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch releases: ${response.status} ${response.statusText}`);
+    }
+    const releases = (await response.json());
+    // Find the latest non-draft extension release
+    for (const release of releases) {
+        if (!release.draft &&
+            release.tag_name.startsWith("absurd-sqlite-extension/")) {
+            // Extract version from tag (e.g., "absurd-sqlite-extension/v0.1.0-alpha.3" -> "v0.1.0-alpha.3")
+            return release.tag_name.replace("absurd-sqlite-extension/", "");
+        }
+    }
+    throw new Error("No extension releases found");
+}
+async function downloadAsset(owner, repo, tag, assetName, destPath, expectedChecksum) {
+    const url = `https://github.com/${owner}/${repo}/releases/download/${tag}/${assetName}`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to download extension: ${response.status} ${response.statusText} from ${url}`);
+    }
+    const buffer = await response.arrayBuffer();
+    (0, node_fs_1.writeFileSync)(destPath, Buffer.from(buffer));
+    // Verify checksum if provided
+    if (expectedChecksum) {
+        const actualChecksum = calculateChecksum(destPath);
+        if (actualChecksum !== expectedChecksum.toLowerCase()) {
+            throw new Error(`Checksum verification failed. Expected: ${expectedChecksum.toLowerCase()}, Got: ${actualChecksum}`);
+        }
+    }
+    // Make the extension executable on Unix-like systems
+    if (process.platform !== "win32") {
+        (0, node_fs_1.chmodSync)(destPath, 0o755);
+    }
+}
+function calculateChecksum(filePath) {
+    const fileBuffer = (0, node_fs_1.readFileSync)(filePath);
+    const hash = (0, node_crypto_1.createHash)("sha256");
+    hash.update(fileBuffer);
+    return hash.digest("hex");
+}
+function getCachedPath(cacheDir, version, platform) {
+    // Use a consistent name that SQLite expects: libabsurd.{ext}
+    const ext = platform.ext;
+    return (0, node_path_1.join)(cacheDir, version, `libabsurd.${ext}`);
+}
+/**
+ * Downloads the absurd-sqlite extension from GitHub releases.
+ * Returns the path to the downloaded extension file.
+ *
+ * @param options - Download options
+ * @returns Path to the extension file
+ *
+ * @example
+ * ```typescript
+ * import { downloadExtension } from "@absurd-sqlite/sdk";
+ *
+ * // Download latest version
+ * const extensionPath = await downloadExtension();
+ *
+ * // Download specific version
+ * const extensionPath = await downloadExtension({ version: "v0.1.0-alpha.3" });
+ *
+ * // Download with checksum verification
+ * const extensionPath = await downloadExtension({
+ *   version: "v0.1.0-alpha.3",
+ *   expectedChecksum: "abc123..."
+ * });
+ * ```
+ */
+async function downloadExtension(options = {}) {
+    const owner = options.owner ?? "b4fun";
+    const repo = options.repo ?? "absurd-sqlite";
+    const cacheDir = options.cacheDir ?? getDefaultCacheDir();
+    const force = options.force ?? false;
+    // Resolve version
+    let version = options.version ?? "latest";
+    if (version === "latest") {
+        version = await fetchLatestVersion(owner, repo);
+    }
+    // Get platform info
+    const platform = getPlatformInfo();
+    const assetName = getAssetName(version, platform);
+    const tag = getTag(version);
+    // Check cache
+    const cachedPath = getCachedPath(cacheDir, version, platform);
+    if (!force && (0, node_fs_1.existsSync)(cachedPath)) {
+        // If checksum is provided, verify cached file
+        if (options.expectedChecksum) {
+            const actualChecksum = calculateChecksum(cachedPath);
+            if (actualChecksum !== options.expectedChecksum.toLowerCase()) {
+                throw new Error(`Cached file checksum verification failed. Expected: ${options.expectedChecksum.toLowerCase()}, Got: ${actualChecksum}`);
+            }
+        }
+        return cachedPath;
+    }
+    // Ensure cache directory exists
+    const versionDir = (0, node_path_1.join)(cacheDir, version);
+    (0, node_fs_1.mkdirSync)(versionDir, { recursive: true });
+    // Download asset
+    await downloadAsset(owner, repo, tag, assetName, cachedPath, options.expectedChecksum);
+    return cachedPath;
+}
+/**
+ * Resolves the extension path, either from the provided path, environment variable,
+ * or by downloading from GitHub releases.
+ *
+ * @param extensionPath - Optional path to the extension file
+ * @param downloadOptions - Options for downloading if no path is provided
+ * @returns Path to the extension file
+ *
+ * @example
+ * ```typescript
+ * import { resolveExtensionPath } from "@absurd-sqlite/sdk";
+ *
+ * // Use provided path
+ * const path1 = await resolveExtensionPath("/path/to/extension.so");
+ *
+ * // Use environment variable or download
+ * const path2 = await resolveExtensionPath();
+ * ```
+ */
+async function resolveExtensionPath(extensionPath, downloadOptions) {
+    // If path is provided, use it
+    if (extensionPath) {
+        return extensionPath;
+    }
+    // Try environment variable
+    const envPath = process.env.ABSURD_SQLITE_EXTENSION_PATH;
+    if (envPath) {
+        return envPath;
+    }
+    // Download from GitHub releases
+    return downloadExtension(downloadOptions);
+}

package/dist/cjs/index.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Absurd = void 0;
+exports.Absurd = exports.resolveExtensionPath = exports.downloadExtension = void 0;
 const absurd_sdk_1 = require("absurd-sdk");
 const sqlite_1 = require("./sqlite");
+var extension_downloader_1 = require("./extension-downloader");
+Object.defineProperty(exports, "downloadExtension", { enumerable: true, get: function () { return extension_downloader_1.downloadExtension; } });
+Object.defineProperty(exports, "resolveExtensionPath", { enumerable: true, get: function () { return extension_downloader_1.resolveExtensionPath; } });
 class Absurd extends absurd_sdk_1.Absurd {
     db;
     constructor(db, extensionPath) {

package/dist/extension-downloader.d.ts

@@ -0,0 +1,76 @@
+export interface DownloadExtensionOptions {
+    /**
+     * Version of the extension to download. If not specified, uses "latest".
+     * Examples: "v0.1.0-alpha.3", "latest"
+     */
+    version?: string;
+    /**
+     * GitHub repository owner. Defaults to "b4fun".
+     */
+    owner?: string;
+    /**
+     * GitHub repository name. Defaults to "absurd-sqlite".
+     */
+    repo?: string;
+    /**
+     * Custom cache directory for storing downloaded extensions.
+     * If not specified, uses a default cache directory in user's home.
+     */
+    cacheDir?: string;
+    /**
+     * Force re-download even if cached version exists.
+     */
+    force?: boolean;
+    /**
+     * Expected SHA256 checksum of the downloaded file for validation.
+     * If provided, the downloaded file's checksum will be verified against this value.
+     * If the checksum doesn't match, an error will be thrown.
+     */
+    expectedChecksum?: string;
+}
+/**
+ * Downloads the absurd-sqlite extension from GitHub releases.
+ * Returns the path to the downloaded extension file.
+ *
+ * @param options - Download options
+ * @returns Path to the extension file
+ *
+ * @example
+ * ```typescript
+ * import { downloadExtension } from "@absurd-sqlite/sdk";
+ *
+ * // Download latest version
+ * const extensionPath = await downloadExtension();
+ *
+ * // Download specific version
+ * const extensionPath = await downloadExtension({ version: "v0.1.0-alpha.3" });
+ *
+ * // Download with checksum verification
+ * const extensionPath = await downloadExtension({
+ *   version: "v0.1.0-alpha.3",
+ *   expectedChecksum: "abc123..."
+ * });
+ * ```
+ */
+export declare function downloadExtension(options?: DownloadExtensionOptions): Promise<string>;
+/**
+ * Resolves the extension path, either from the provided path, environment variable,
+ * or by downloading from GitHub releases.
+ *
+ * @param extensionPath - Optional path to the extension file
+ * @param downloadOptions - Options for downloading if no path is provided
+ * @returns Path to the extension file
+ *
+ * @example
+ * ```typescript
+ * import { resolveExtensionPath } from "@absurd-sqlite/sdk";
+ *
+ * // Use provided path
+ * const path1 = await resolveExtensionPath("/path/to/extension.so");
+ *
+ * // Use environment variable or download
+ * const path2 = await resolveExtensionPath();
+ * ```
+ */
+export declare function resolveExtensionPath(extensionPath?: string, downloadOptions?: DownloadExtensionOptions): Promise<string>;
+//# sourceMappingURL=extension-downloader.d.ts.map

package/dist/extension-downloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-downloader.d.ts","sourceRoot":"","sources":["../src/extension-downloader.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAkJD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,MAAM,CAAC,CAyCjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,oBAAoB,CACxC,aAAa,CAAC,EAAE,MAAM,EACtB,eAAe,CAAC,EAAE,wBAAwB,GACzC,OAAO,CAAC,MAAM,CAAC,CAcjB"}

package/dist/extension-downloader.js

@@ -0,0 +1,186 @@
+import { existsSync, mkdirSync, writeFileSync, chmodSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+function getPlatformInfo() {
+    const platform = process.platform;
+    const arch = process.arch;
+    let os;
+    let ext;
+    switch (platform) {
+        case "darwin":
+            os = "macOS";
+            ext = "dylib";
+            break;
+        case "linux":
+            os = "Linux";
+            ext = "so";
+            break;
+        case "win32":
+            os = "Windows";
+            ext = "dll";
+            break;
+        default:
+            throw new Error(`Unsupported platform: ${platform}`);
+    }
+    let archStr;
+    switch (arch) {
+        case "x64":
+            archStr = "X64";
+            break;
+        case "arm64":
+            archStr = "ARM64";
+            break;
+        default:
+            throw new Error(`Unsupported architecture: ${arch}`);
+    }
+    return { os, arch: archStr, ext };
+}
+function getDefaultCacheDir() {
+    return join(homedir(), ".cache", "absurd-sqlite", "extensions");
+}
+function getAssetName(version, platform) {
+    // Format: absurd-absurd-sqlite-extension-vX.Y.Z-{OS}-{ARCH}.{ext}
+    return `absurd-absurd-sqlite-extension-${version}-${platform.os}-${platform.arch}.${platform.ext}`;
+}
+function getTag(version) {
+    return `absurd-sqlite-extension/${version}`;
+}
+async function fetchLatestVersion(owner, repo) {
+    const url = `https://api.github.com/repos/${owner}/${repo}/releases`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch releases: ${response.status} ${response.statusText}`);
+    }
+    const releases = (await response.json());
+    // Find the latest non-draft extension release
+    for (const release of releases) {
+        if (!release.draft &&
+            release.tag_name.startsWith("absurd-sqlite-extension/")) {
+            // Extract version from tag (e.g., "absurd-sqlite-extension/v0.1.0-alpha.3" -> "v0.1.0-alpha.3")
+            return release.tag_name.replace("absurd-sqlite-extension/", "");
+        }
+    }
+    throw new Error("No extension releases found");
+}
+async function downloadAsset(owner, repo, tag, assetName, destPath, expectedChecksum) {
+    const url = `https://github.com/${owner}/${repo}/releases/download/${tag}/${assetName}`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to download extension: ${response.status} ${response.statusText} from ${url}`);
+    }
+    const buffer = await response.arrayBuffer();
+    writeFileSync(destPath, Buffer.from(buffer));
+    // Verify checksum if provided
+    if (expectedChecksum) {
+        const actualChecksum = calculateChecksum(destPath);
+        if (actualChecksum !== expectedChecksum.toLowerCase()) {
+            throw new Error(`Checksum verification failed. Expected: ${expectedChecksum.toLowerCase()}, Got: ${actualChecksum}`);
+        }
+    }
+    // Make the extension executable on Unix-like systems
+    if (process.platform !== "win32") {
+        chmodSync(destPath, 0o755);
+    }
+}
+function calculateChecksum(filePath) {
+    const fileBuffer = readFileSync(filePath);
+    const hash = createHash("sha256");
+    hash.update(fileBuffer);
+    return hash.digest("hex");
+}
+function getCachedPath(cacheDir, version, platform) {
+    // Use a consistent name that SQLite expects: libabsurd.{ext}
+    const ext = platform.ext;
+    return join(cacheDir, version, `libabsurd.${ext}`);
+}
+/**
+ * Downloads the absurd-sqlite extension from GitHub releases.
+ * Returns the path to the downloaded extension file.
+ *
+ * @param options - Download options
+ * @returns Path to the extension file
+ *
+ * @example
+ * ```typescript
+ * import { downloadExtension } from "@absurd-sqlite/sdk";
+ *
+ * // Download latest version
+ * const extensionPath = await downloadExtension();
+ *
+ * // Download specific version
+ * const extensionPath = await downloadExtension({ version: "v0.1.0-alpha.3" });
+ *
+ * // Download with checksum verification
+ * const extensionPath = await downloadExtension({
+ *   version: "v0.1.0-alpha.3",
+ *   expectedChecksum: "abc123..."
+ * });
+ * ```
+ */
+export async function downloadExtension(options = {}) {
+    const owner = options.owner ?? "b4fun";
+    const repo = options.repo ?? "absurd-sqlite";
+    const cacheDir = options.cacheDir ?? getDefaultCacheDir();
+    const force = options.force ?? false;
+    // Resolve version
+    let version = options.version ?? "latest";
+    if (version === "latest") {
+        version = await fetchLatestVersion(owner, repo);
+    }
+    // Get platform info
+    const platform = getPlatformInfo();
+    const assetName = getAssetName(version, platform);
+    const tag = getTag(version);
+    // Check cache
+    const cachedPath = getCachedPath(cacheDir, version, platform);
+    if (!force && existsSync(cachedPath)) {
+        // If checksum is provided, verify cached file
+        if (options.expectedChecksum) {
+            const actualChecksum = calculateChecksum(cachedPath);
+            if (actualChecksum !== options.expectedChecksum.toLowerCase()) {
+                throw new Error(`Cached file checksum verification failed. Expected: ${options.expectedChecksum.toLowerCase()}, Got: ${actualChecksum}`);
+            }
+        }
+        return cachedPath;
+    }
+    // Ensure cache directory exists
+    const versionDir = join(cacheDir, version);
+    mkdirSync(versionDir, { recursive: true });
+    // Download asset
+    await downloadAsset(owner, repo, tag, assetName, cachedPath, options.expectedChecksum);
+    return cachedPath;
+}
+/**
+ * Resolves the extension path, either from the provided path, environment variable,
+ * or by downloading from GitHub releases.
+ *
+ * @param extensionPath - Optional path to the extension file
+ * @param downloadOptions - Options for downloading if no path is provided
+ * @returns Path to the extension file
+ *
+ * @example
+ * ```typescript
+ * import { resolveExtensionPath } from "@absurd-sqlite/sdk";
+ *
+ * // Use provided path
+ * const path1 = await resolveExtensionPath("/path/to/extension.so");
+ *
+ * // Use environment variable or download
+ * const path2 = await resolveExtensionPath();
+ * ```
+ */
+export async function resolveExtensionPath(extensionPath, downloadOptions) {
+    // If path is provided, use it
+    if (extensionPath) {
+        return extensionPath;
+    }
+    // Try environment variable
+    const envPath = process.env.ABSURD_SQLITE_EXTENSION_PATH;
+    if (envPath) {
+        return envPath;
+    }
+    // Download from GitHub releases
+    return downloadExtension(downloadOptions);
+}
+//# sourceMappingURL=extension-downloader.js.map

package/dist/extension-downloader.js.map

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

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { Absurd as AbsurdBase } from "absurd-sdk";
 import type { AbsurdClient } from "./absurd-types";
 import type { SQLiteDatabase } from "./sqlite-types";
 export type { AbsurdClient, Queryable, Worker } from "./absurd-types";
+export { downloadExtension, resolveExtensionPath, type DownloadExtensionOptions, } from "./extension-downloader";
 export type { AbsurdHooks, AbsurdOptions, CancellationPolicy, ClaimedTask, JsonObject, JsonValue, RetryStrategy, SpawnOptions, SpawnResult, TaskContext, TaskHandler, TaskRegistrationOptions, WorkerOptions, } from "absurd-sdk";
 export type { SQLiteBindParams, SQLiteBindValue, SQLiteColumnDefinition, SQLiteDatabase, SQLiteRestBindParams, SQLiteStatement, SQLiteVerboseLog, } from "./sqlite-types";
 export declare class Absurd extends AbsurdBase implements AbsurdClient {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGrD,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACtE,YAAY,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,SAAS,EACT,aAAa,EACb,YAAY,EACZ,WAAW,EACX,WAAW,EACX,WAAW,EACX,uBAAuB,EACvB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,qBAAa,MAAO,SAAQ,UAAW,YAAW,YAAY;IAC5D,OAAO,CAAC,EAAE,CAAiB;gBAEf,EAAE,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM;IAO/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGrD,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,wBAAwB,GAC9B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,SAAS,EACT,aAAa,EACb,YAAY,EACZ,WAAW,EACX,WAAW,EACX,WAAW,EACX,uBAAuB,EACvB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,qBAAa,MAAO,SAAQ,UAAW,YAAW,YAAY;IAC5D,OAAO,CAAC,EAAE,CAAiB;gBAEf,EAAE,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM;IAO/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/index.js

@@ -1,5 +1,6 @@
 import { Absurd as AbsurdBase } from "absurd-sdk";
 import { SqliteConnection } from "./sqlite";
+export { downloadExtension, resolveExtensionPath, } from "./extension-downloader";
 export class Absurd extends AbsurdBase {
     db;
     constructor(db, extensionPath) {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,YAAY,CAAC;AAIlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AA4B5C,MAAM,OAAO,MAAO,SAAQ,UAAU;IAC5B,EAAE,CAAiB;IAE3B,YAAY,EAAkB,EAAE,aAAqB;QACnD,EAAE,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;QAChC,MAAM,SAAS,GAAG,IAAI,gBAAgB,CAAC,EAAE,CAAC,CAAC;QAC3C,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;CACF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,YAAY,CAAC;AAIlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAG5C,OAAO,EACL,iBAAiB,EACjB,oBAAoB,GAErB,MAAM,wBAAwB,CAAC;AA0BhC,MAAM,OAAO,MAAO,SAAQ,UAAU;IAC5B,EAAE,CAAiB;IAE3B,YAAY,EAAkB,EAAE,aAAqB;QACnD,EAAE,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;QAChC,MAAM,SAAS,GAAG,IAAI,gBAAgB,CAAC,EAAE,CAAC,CAAC;QAC3C,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absurd-sqlite/sdk",
-  "version": "0.2.1-alpha.0",
+  "version": "0.2.1-alpha.2",
   "description": "TypeScript SDK for Absurd-SQLite - SQLite-based durable task execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,7 +36,7 @@
     "better-sqlite3": "^12.5.0"
   },
   "dependencies": {
-    "absurd-sdk": "~0.0.7"
+    "absurd-sdk": "https://github.com/bcho/absurd/releases/download/sdks%2Ftypescript%2Fv0.0.7/typescript-sdk-v0.0.7.tgz"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
@@ -48,4 +48,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}

package/src/extension-downloader.ts

@@ -0,0 +1,291 @@
+import { existsSync, mkdirSync, writeFileSync, chmodSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+
+export interface DownloadExtensionOptions {
+  /**
+   * Version of the extension to download. If not specified, uses "latest".
+   * Examples: "v0.1.0-alpha.3", "latest"
+   */
+  version?: string;
+
+  /**
+   * GitHub repository owner. Defaults to "b4fun".
+   */
+  owner?: string;
+
+  /**
+   * GitHub repository name. Defaults to "absurd-sqlite".
+   */
+  repo?: string;
+
+  /**
+   * Custom cache directory for storing downloaded extensions.
+   * If not specified, uses a default cache directory in user's home.
+   */
+  cacheDir?: string;
+
+  /**
+   * Force re-download even if cached version exists.
+   */
+  force?: boolean;
+
+  /**
+   * Expected SHA256 checksum of the downloaded file for validation.
+   * If provided, the downloaded file's checksum will be verified against this value.
+   * If the checksum doesn't match, an error will be thrown.
+   */
+  expectedChecksum?: string;
+}
+
+interface PlatformInfo {
+  os: string;
+  arch: string;
+  ext: string;
+}
+
+function getPlatformInfo(): PlatformInfo {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  let os: string;
+  let ext: string;
+
+  switch (platform) {
+    case "darwin":
+      os = "macOS";
+      ext = "dylib";
+      break;
+    case "linux":
+      os = "Linux";
+      ext = "so";
+      break;
+    case "win32":
+      os = "Windows";
+      ext = "dll";
+      break;
+    default:
+      throw new Error(`Unsupported platform: ${platform}`);
+  }
+
+  let archStr: string;
+  switch (arch) {
+    case "x64":
+      archStr = "X64";
+      break;
+    case "arm64":
+      archStr = "ARM64";
+      break;
+    default:
+      throw new Error(`Unsupported architecture: ${arch}`);
+  }
+
+  return { os, arch: archStr, ext };
+}
+
+function getDefaultCacheDir(): string {
+  return join(homedir(), ".cache", "absurd-sqlite", "extensions");
+}
+
+function getAssetName(version: string, platform: PlatformInfo): string {
+  // Format: absurd-absurd-sqlite-extension-vX.Y.Z-{OS}-{ARCH}.{ext}
+  return `absurd-absurd-sqlite-extension-${version}-${platform.os}-${platform.arch}.${platform.ext}`;
+}
+
+function getTag(version: string): string {
+  return `absurd-sqlite-extension/${version}`;
+}
+
+async function fetchLatestVersion(
+  owner: string,
+  repo: string
+): Promise<string> {
+  const url = `https://api.github.com/repos/${owner}/${repo}/releases`;
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch releases: ${response.status} ${response.statusText}`
+    );
+  }
+
+  const releases = (await response.json()) as Array<{
+    tag_name: string;
+    prerelease: boolean;
+    draft: boolean;
+  }>;
+
+  // Find the latest non-draft extension release
+  for (const release of releases) {
+    if (
+      !release.draft &&
+      release.tag_name.startsWith("absurd-sqlite-extension/")
+    ) {
+      // Extract version from tag (e.g., "absurd-sqlite-extension/v0.1.0-alpha.3" -> "v0.1.0-alpha.3")
+      return release.tag_name.replace("absurd-sqlite-extension/", "");
+    }
+  }
+
+  throw new Error("No extension releases found");
+}
+
+async function downloadAsset(
+  owner: string,
+  repo: string,
+  tag: string,
+  assetName: string,
+  destPath: string,
+  expectedChecksum?: string
+): Promise<void> {
+  const url = `https://github.com/${owner}/${repo}/releases/download/${tag}/${assetName}`;
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download extension: ${response.status} ${response.statusText} from ${url}`
+    );
+  }
+
+  const buffer = await response.arrayBuffer();
+  writeFileSync(destPath, Buffer.from(buffer));
+
+  // Verify checksum if provided
+  if (expectedChecksum) {
+    const actualChecksum = calculateChecksum(destPath);
+    if (actualChecksum !== expectedChecksum.toLowerCase()) {
+      throw new Error(
+        `Checksum verification failed. Expected: ${expectedChecksum.toLowerCase()}, Got: ${actualChecksum}`
+      );
+    }
+  }
+
+  // Make the extension executable on Unix-like systems
+  if (process.platform !== "win32") {
+    chmodSync(destPath, 0o755);
+  }
+}
+
+function calculateChecksum(filePath: string): string {
+  const fileBuffer = readFileSync(filePath);
+  const hash = createHash("sha256");
+  hash.update(fileBuffer);
+  return hash.digest("hex");
+}
+
+function getCachedPath(
+  cacheDir: string,
+  version: string,
+  platform: PlatformInfo
+): string {
+  // Use a consistent name that SQLite expects: libabsurd.{ext}
+  const ext = platform.ext;
+  return join(cacheDir, version, `libabsurd.${ext}`);
+}
+
+/**
+ * Downloads the absurd-sqlite extension from GitHub releases.
+ * Returns the path to the downloaded extension file.
+ *
+ * @param options - Download options
+ * @returns Path to the extension file
+ *
+ * @example
+ * ```typescript
+ * import { downloadExtension } from "@absurd-sqlite/sdk";
+ *
+ * // Download latest version
+ * const extensionPath = await downloadExtension();
+ *
+ * // Download specific version
+ * const extensionPath = await downloadExtension({ version: "v0.1.0-alpha.3" });
+ *
+ * // Download with checksum verification
+ * const extensionPath = await downloadExtension({
+ *   version: "v0.1.0-alpha.3",
+ *   expectedChecksum: "abc123..."
+ * });
+ * ```
+ */
+export async function downloadExtension(
+  options: DownloadExtensionOptions = {}
+): Promise<string> {
+  const owner = options.owner ?? "b4fun";
+  const repo = options.repo ?? "absurd-sqlite";
+  const cacheDir = options.cacheDir ?? getDefaultCacheDir();
+  const force = options.force ?? false;
+
+  // Resolve version
+  let version = options.version ?? "latest";
+  if (version === "latest") {
+    version = await fetchLatestVersion(owner, repo);
+  }
+
+  // Get platform info
+  const platform = getPlatformInfo();
+  const assetName = getAssetName(version, platform);
+  const tag = getTag(version);
+
+  // Check cache
+  const cachedPath = getCachedPath(cacheDir, version, platform);
+
+  if (!force && existsSync(cachedPath)) {
+    // If checksum is provided, verify cached file
+    if (options.expectedChecksum) {
+      const actualChecksum = calculateChecksum(cachedPath);
+      if (actualChecksum !== options.expectedChecksum.toLowerCase()) {
+        throw new Error(
+          `Cached file checksum verification failed. Expected: ${options.expectedChecksum.toLowerCase()}, Got: ${actualChecksum}`
+        );
+      }
+    }
+    return cachedPath;
+  }
+
+  // Ensure cache directory exists
+  const versionDir = join(cacheDir, version);
+  mkdirSync(versionDir, { recursive: true });
+
+  // Download asset
+  await downloadAsset(owner, repo, tag, assetName, cachedPath, options.expectedChecksum);
+
+  return cachedPath;
+}
+
+/**
+ * Resolves the extension path, either from the provided path, environment variable,
+ * or by downloading from GitHub releases.
+ *
+ * @param extensionPath - Optional path to the extension file
+ * @param downloadOptions - Options for downloading if no path is provided
+ * @returns Path to the extension file
+ *
+ * @example
+ * ```typescript
+ * import { resolveExtensionPath } from "@absurd-sqlite/sdk";
+ *
+ * // Use provided path
+ * const path1 = await resolveExtensionPath("/path/to/extension.so");
+ *
+ * // Use environment variable or download
+ * const path2 = await resolveExtensionPath();
+ * ```
+ */
+export async function resolveExtensionPath(
+  extensionPath?: string,
+  downloadOptions?: DownloadExtensionOptions
+): Promise<string> {
+  // If path is provided, use it
+  if (extensionPath) {
+    return extensionPath;
+  }
+
+  // Try environment variable
+  const envPath = process.env.ABSURD_SQLITE_EXTENSION_PATH;
+  if (envPath) {
+    return envPath;
+  }
+
+  // Download from GitHub releases
+  return downloadExtension(downloadOptions);
+}

package/src/index.ts

@@ -5,6 +5,11 @@ import type { SQLiteDatabase } from "./sqlite-types";
 import { SqliteConnection } from "./sqlite";
 
 export type { AbsurdClient, Queryable, Worker } from "./absurd-types";
+export {
+  downloadExtension,
+  resolveExtensionPath,
+  type DownloadExtensionOptions,
+} from "./extension-downloader";
 export type {
   AbsurdHooks,
   AbsurdOptions,

package/test/extension-downloader.test.ts

@@ -0,0 +1,203 @@
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  downloadExtension,
+  resolveExtensionPath,
+} from "../src/extension-downloader";
+
+let tempCacheDir: string | null = null;
+
+afterEach(() => {
+  if (tempCacheDir) {
+    rmSync(tempCacheDir, { recursive: true, force: true });
+    tempCacheDir = null;
+  }
+});
+
+// Helper function to calculate checksum of a file
+async function getFileChecksum(filePath: string): Promise<string> {
+  const { createHash } = await import("node:crypto");
+  const { readFileSync } = await import("node:fs");
+  const fileBuffer = readFileSync(filePath);
+  const hash = createHash("sha256");
+  hash.update(fileBuffer);
+  return hash.digest("hex");
+}
+
+describe("downloadExtension", () => {
+  it("downloads specific version", async () => {
+    tempCacheDir = mkdtempSync(join(tmpdir(), "absurd-ext-cache-"));
+
+    const extensionPath = await downloadExtension({
+      version: "v0.1.0-alpha.3",
+      cacheDir: tempCacheDir,
+    });
+
+    expect(existsSync(extensionPath)).toBe(true);
+    expect(extensionPath).toContain("v0.1.0-alpha.3");
+
+    // Verify it has the right extension
+    const platform = process.platform;
+    if (platform === "darwin") {
+      expect(extensionPath).toMatch(/libabsurd\.dylib$/);
+    } else if (platform === "linux") {
+      expect(extensionPath).toMatch(/libabsurd\.so$/);
+    } else if (platform === "win32") {
+      expect(extensionPath).toMatch(/libabsurd\.dll$/);
+    }
+  }, 60000);
+
+  it("uses cached version on second call", async () => {
+    tempCacheDir = mkdtempSync(join(tmpdir(), "absurd-ext-cache-"));
+
+    const path1 = await downloadExtension({
+      version: "v0.1.0-alpha.3",
+      cacheDir: tempCacheDir,
+    });
+
+    const path2 = await downloadExtension({
+      version: "v0.1.0-alpha.3",
+      cacheDir: tempCacheDir,
+    });
+
+    expect(path1).toBe(path2);
+  }, 60000);
+
+  it("forces re-download when force=true", async () => {
+    tempCacheDir = mkdtempSync(join(tmpdir(), "absurd-ext-cache-"));
+
+    const path1 = await downloadExtension({
+      version: "v0.1.0-alpha.3",
+      cacheDir: tempCacheDir,
+    });
+
+    // Delete the cached file
+    rmSync(path1);
+    expect(existsSync(path1)).toBe(false);
+
+    // Download again with force
+    const path2 = await downloadExtension({
+      version: "v0.1.0-alpha.3",
+      cacheDir: tempCacheDir,
+      force: true,
+    });
+
+    expect(existsSync(path2)).toBe(true);
+    expect(path2).toBe(path1); // Same path
+  }, 60000);
+
+  it("validates checksum when provided", async () => {
+    tempCacheDir = mkdtempSync(join(tmpdir(), "absurd-ext-cache-"));
+
+    // First download to get the file
+    const extensionPath = await downloadExtension({
+      version: "v0.1.0-alpha.3",
+      cacheDir: tempCacheDir,
+    });
+
+    // Calculate the actual checksum
+    const actualChecksum = await getFileChecksum(extensionPath);
+
+    // Clear cache
+    rmSync(extensionPath);
+
+    // Download again with correct checksum - should succeed
+    const path1 = await downloadExtension({
+      version: "v0.1.0-alpha.3",
+      cacheDir: tempCacheDir,
+      expectedChecksum: actualChecksum,
+    });
+
+    expect(existsSync(path1)).toBe(true);
+
+    // Try with wrong checksum - should fail
+    rmSync(path1);
+    await expect(
+      downloadExtension({
+        version: "v0.1.0-alpha.3",
+        cacheDir: tempCacheDir,
+        expectedChecksum: "0000000000000000000000000000000000000000000000000000000000000000",
+      })
+    ).rejects.toThrow(/Checksum verification failed/);
+  }, 60000);
+
+  it("validates checksum of cached file", async () => {
+    tempCacheDir = mkdtempSync(join(tmpdir(), "absurd-ext-cache-"));
+
+    // First download to get the file
+    const extensionPath = await downloadExtension({
+      version: "v0.1.0-alpha.3",
+      cacheDir: tempCacheDir,
+    });
+
+    // Calculate the actual checksum
+    const actualChecksum = await getFileChecksum(extensionPath);
+
+    // Use cached file with correct checksum - should succeed
+    const path1 = await downloadExtension({
+      version: "v0.1.0-alpha.3",
+      cacheDir: tempCacheDir,
+      expectedChecksum: actualChecksum,
+    });
+
+    expect(existsSync(path1)).toBe(true);
+
+    // Try with wrong checksum on cached file - should fail
+    await expect(
+      downloadExtension({
+        version: "v0.1.0-alpha.3",
+        cacheDir: tempCacheDir,
+        expectedChecksum: "0000000000000000000000000000000000000000000000000000000000000000",
+      })
+    ).rejects.toThrow(/Cached file checksum verification failed/);
+  }, 60000);
+});
+
+describe("resolveExtensionPath", () => {
+  it("returns provided path when given", async () => {
+    const providedPath = "/custom/path/to/extension.so";
+    const resolved = await resolveExtensionPath(providedPath);
+    expect(resolved).toBe(providedPath);
+  });
+
+  it("uses environment variable when no path provided", async () => {
+    const envPath = "/env/path/to/extension.so";
+    const originalEnv = process.env.ABSURD_SQLITE_EXTENSION_PATH;
+
+    try {
+      process.env.ABSURD_SQLITE_EXTENSION_PATH = envPath;
+      const resolved = await resolveExtensionPath();
+      expect(resolved).toBe(envPath);
+    } finally {
+      if (originalEnv !== undefined) {
+        process.env.ABSURD_SQLITE_EXTENSION_PATH = originalEnv;
+      } else {
+        delete process.env.ABSURD_SQLITE_EXTENSION_PATH;
+      }
+    }
+  });
+
+  it("downloads when no path or env var provided", async () => {
+    tempCacheDir = mkdtempSync(join(tmpdir(), "absurd-ext-cache-"));
+    const originalEnv = process.env.ABSURD_SQLITE_EXTENSION_PATH;
+
+    try {
+      delete process.env.ABSURD_SQLITE_EXTENSION_PATH;
+
+      const resolved = await resolveExtensionPath(undefined, {
+        version: "v0.1.0-alpha.3",
+        cacheDir: tempCacheDir,
+      });
+
+      expect(existsSync(resolved)).toBe(true);
+      expect(resolved).toContain(tempCacheDir);
+    } finally {
+      if (originalEnv !== undefined) {
+        process.env.ABSURD_SQLITE_EXTENSION_PATH = originalEnv;
+      }
+    }
+  }, 60000);
+});