litescrape-sdk 0.1.0

package/dist/esm/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,CAAC,CAAC,OAAO,UAAU,CAAC,oCAAqB,CAAC;AAC7E,eAAO,MAAM,IAAI,2HAA2E,CAAC;AAC7F,eAAO,MAAM,MAAM,8KAUS,CAAC;AAC7B,eAAO,MAAM,OAAO,sMAAgC,CAAC;AACrD,eAAO,MAAM,OAAO;;;;;;;;;;;;;qIAUkE,CAAC;AACvF,eAAO,MAAM,IAAI;;;6GAE0F,CAAC;AAC5G,eAAO,MAAM,aAAa;;;IAAoD,CAAC;AAC/E,eAAO,MAAM,cAAc,aAAoC,CAAC;AAChE,eAAO,MAAM,MAAM;;;;EAA0C,CAAC;AAE9D,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACtC,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,aAAa,KAAK,IAAI,CAAC;AACtE,eAAO,MAAM,KAAK,YAAa,CAAC,CAAC,aAAa,WAAW,MAAM,SAAQ,MAAM,EAAE,SAC1B,CAAC;AACtD,eAAO,MAAM,GAAG,WAAY,MAAM,SAAS,MAAM,YAA0D,CAAC;AAC5G,eAAO,MAAM,UAAU,cACT,MAAM,EAAE,KAAG,IAGtB,CAAC;AACJ,eAAO,MAAM,UAAU,cACT,MAAM,EAAE,KAAG,IAItB,CAAC;AACJ,eAAO,MAAM,SAAS,cACR,MAAM,EAAE,KAAG,IAItB,CAAC;AACJ,eAAO,MAAM,MAAM,MACb,MAAM,KAAK,MAAM,KAAG,IAGvB,CAAC;AACJ,eAAO,MAAM,QAAQ,UACX,MAAM,cAAc,MAAM,KAAG,IAGpC,CAAC;AAEJ,kGAAkG;AAClG,qBAAa,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;;IAClD,SAAiB,QAAQ,EAAE,CAAC,CAAC;IAC7B,SAAiB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAGzC,YAAY,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,CAAC,CAAA;KAAE,EAAE,SAAS,CAAC,EAAE,MAAM,EAK7E;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMpC;IAED,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAErC;IAED,gGAAgG;IAChG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAGjC;CACF;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM;IAC3D,KAAK,MAAM,EAAE,KAAK,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzD,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,SAAS,CAAC,CAAC,WAAW,EACzE,QAAQ,EAAE,CAAC,EACX,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,KAAK,EACZ,KAAK,GAAE,IAAI,EAAO,GACjB,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAuB5E"}

package/dist/esm/validation.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { ValidationError } from "./errors.js";
+export const optional = (schema) => schema.nullish();
+export const text = z.union([z.string(), z.number().finite(), z.bigint()]).transform(String);
+export const number = z
+    .union([
+    z.number(),
+    z
+        .string()
+        .trim()
+        .regex(/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/)
+        .transform(Number),
+    z.boolean().transform(Number),
+])
+    .pipe(z.number().finite());
+export const integer = number.pipe(z.number().int());
+export const boolean = z
+    .union([
+    z.boolean(),
+    z.literal(0),
+    z.literal(1),
+    z
+        .string()
+        .toLowerCase()
+        .pipe(z.enum(["0", "1", "true", "false", "yes", "no", "on", "off", "t", "f", "y", "n"])),
+])
+    .transform((value) => [true, 1, "1", "true", "yes", "on", "t", "y"].includes(value));
+export const flag = z
+    .union([z.enum(["0", "1"]), z.literal(0), z.literal(1), z.boolean()])
+    .transform((value) => (value === true || value === 1 || value === "1" ? "1" : "0"));
+export const strictBoolean = z.union([z.boolean(), z.enum(["true", "false"])]);
+export const timeoutSeconds = z.number().finite().gt(0).max(90);
+export const device = z.enum(["desktop", "tablet", "mobile"]);
+export const issue = (context, message, path = []) => context.addIssue({ code: "custom", message, path });
+export const has = (params, field) => params[field] !== null && params[field] !== undefined;
+export const requireAny = (...fields) => (p, c) => {
+    if (!fields.some((f) => has(p, f)))
+        issue(c, `one of ${fields.join(", ")} is required`);
+};
+export const exactlyOne = (...fields) => (p, c) => {
+    if (fields.filter((f) => has(p, f)).length !== 1)
+        issue(c, `exactly one of ${fields.join(", ")} is required`);
+};
+export const atMostOne = (...fields) => (p, c) => {
+    const found = fields.filter((f) => has(p, f));
+    if (found.length > 1)
+        issue(c, `${found.join(" and ")} cannot be combined`);
+};
+export const paired = (a, b) => (p, c) => {
+    if (has(p, a) !== has(p, b))
+        issue(c, `${a} and ${b} must be given together`);
+};
+export const requires = (field, dependency) => (p, c) => {
+    if (has(p, field) && !has(p, dependency))
+        issue(c, `${field} requires ${dependency}`);
+};
+/** Validated, immutable request. Construct an endpoint class or pass a plain object to scrape. */
+export class ScrapeRequest {
+    #path;
+    constructor(path, params, prototype) {
+        this.#path = path;
+        Object.assign(this, params);
+        if (prototype)
+            Object.setPrototypeOf(this, prototype);
+        Object.freeze(this);
+    }
+    get path() {
+        return this.#path;
+    }
+    queryParams() {
+        return Object.fromEntries(Object.entries(this)
+            .filter(([key, value]) => key !== "endpoint" && value != null)
+            .map(([key, value]) => [key, String(value)]));
+    }
+    query_params() {
+        return this.queryParams();
+    }
+    /** Copy a validated request with a default deadline without revalidating its cursor context. */
+    withTimeout(timeout) {
+        const checked = timeoutSeconds.parse(timeout);
+        return new ScrapeRequest(this.path, { ...this, timeout: checked }, Object.getPrototypeOf(this));
+    }
+}
+export function defineRequest(endpoint, path, shape, rules = []) {
+    const schema = z.strictObject(shape).superRefine((params, ctx) => {
+        for (const rule of rules)
+            rule(params, ctx);
+    });
+    class Request extends ScrapeRequest {
+        static endpoint = endpoint;
+        static path = path;
+        static parameters = Object.freeze(Object.keys(shape));
+        constructor(params) {
+            const result = schema.safeParse(params);
+            if (!result.success)
+                throw new ValidationError([
+                    [
+                        0,
+                        result.error.issues
+                            .map((i) => `${i.path.join(".")}${i.path.length ? ": " : ""}${i.message}`)
+                            .join("; "),
+                    ],
+                ]);
+            super(path, { ...result.data, endpoint });
+        }
+    }
+    return Request;
+}
+//# sourceMappingURL=validation.js.map

package/dist/esm/validation.js.map

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

package/dist/esm/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/esm/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/esm/version.js

@@ -0,0 +1,2 @@
+export const VERSION = "0.1.0";
+//# sourceMappingURL=version.js.map

package/dist/esm/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "litescrape-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Litescrape API: validated, concurrent, retrying calls and durable batches.",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/build-cjs.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tests/tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "test:package": "node scripts/smoke-package.mjs",
+    "lint": "prettier --check . && npm run typecheck",
+    "format": "prettier --write .",
+    "check": "npm run lint && npm test",
+    "prepare": "npm run build",
+    "prepack": "npm run build"
+  },
+  "author": "Litescraper <support@litescrape.com>",
+  "license": "MIT",
+  "homepage": "https://litescrape.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/litescrape/litescrape-sdk-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/litescrape/litescrape-sdk-ts/issues"
+  },
+  "keywords": [
+    "litescrape",
+    "serp",
+    "google",
+    "maps",
+    "reviews",
+    "scraping",
+    "api",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "prettier": "^3.9.8",
+    "typescript": "^7.0.2"
+  }
+}

package/src/batch.ts

@@ -0,0 +1,158 @@
+import { APIError, TransportError, apiError, isObject } from "./errors.js";
+import { JobCache, cacheKeys, newId, type CacheEntry } from "./cache.js";
+import type { AnyRequest } from "./models.js";
+import { Result } from "./result.js";
+import {
+  Semaphore,
+  backoff,
+  each,
+  requestWithRetries,
+  sleep,
+  type Outcome,
+  type RuntimeOptions,
+} from "./runtime.js";
+
+interface BatchOptions extends RuntimeOptions {
+  concurrency?: number;
+  useCache: boolean;
+  cachePath?: string;
+  onResult: (result: Result) => void;
+}
+type Submission = { entry: CacheEntry; outcome: Outcome };
+
+export async function runBatch(items: readonly AnyRequest[], options: BatchOptions): Promise<Result[]> {
+  options.signal?.throwIfAborted();
+  const cache = new JobCache(options.cachePath);
+  const keys = cacheKeys(items, options.apiKey, options.baseUrl);
+  const limit = options.concurrency ?? 32;
+  const semaphores = [new Semaphore(limit)];
+  const started = performance.now();
+  const batchKey = newId();
+  const indices = items.map((_, i) => i);
+  const results: Result[] = new Array(items.length);
+
+  try {
+    const entries = cache.prepareMany(keys, options.useCache, batchKey, items.length);
+    const pollOnce = (jobId: string) =>
+      requestWithRetries(`/api/batch/jobs/${encodeURIComponent(jobId)}`, { ...options, semaphores });
+    const replace = (index: number) => cache.prepareMany([keys[index]!], false, batchKey, items.length)[0]!;
+
+    const submit = async (index: number, replaceExpired = false): Promise<Submission> => {
+      let entry = replaceExpired ? replace(index) : entries[index]!;
+      if (entry.job_id) {
+        const outcome = await pollOnce(entry.job_id);
+        // Only positive evidence of expiry/missing jobs permits a fresh reservation.
+        if (
+          (!outcome.error && outcome.data?.state !== "expired") ||
+          (outcome.error && ![404, 410].includes(outcome.statusCode ?? 0))
+        )
+          return { entry, outcome };
+        entry = replace(index);
+      }
+      const outcome = await requestWithRetries(items[index]!.path + "/async", {
+        ...options,
+        semaphores,
+        method: "POST",
+        body: items[index]!.queryParams(),
+        acceptedStatuses: [200, 202],
+        headers: {
+          "Idempotency-Key": entry.submission,
+          "X-Litescrape-Batch-ID": entry.batch_key,
+          "X-Litescrape-Batch-Size": String(entry.batch_size),
+        },
+      });
+      if (!outcome.error) {
+        const job = outcome.data!;
+        if (typeof job.job_id !== "string" || !job.job_id)
+          outcome.error = new TransportError("Batch submission returned no job ID.", { retryable: true });
+        else {
+          entry.job_id = job.job_id;
+          cache.save(keys[index]!, entry.submission, job.job_id, job.expires_at);
+          if (job.state === "expired" && options.useCache && !replaceExpired) return submit(index, true);
+        }
+      }
+      return { entry, outcome };
+    };
+
+    const submissions: Submission[] = new Array(items.length);
+    await each(indices, limit, async (index) => {
+      submissions[index] = await submit(index);
+    });
+
+    const resolve = (index: number, { entry, outcome }: Submission): Result | null => {
+      if (!outcome.error) {
+        const job = outcome.data!;
+        if (typeof job.job_id !== "string" || !job.job_id || job.job_id !== entry.job_id) {
+          outcome.error = new TransportError("Batch job returned an invalid job ID.", { retryable: false });
+        } else if (job.state === "succeeded" || job.state === "failed") {
+          const status = job.status_code;
+          const payload = job.response;
+          if (
+            typeof status !== "number" ||
+            !Number.isInteger(status) ||
+            status < 100 ||
+            status > 599 ||
+            !isObject(payload) ||
+            (job.state === "succeeded") !== (status === 200)
+          ) {
+            outcome.error = new TransportError("Batch job returned an invalid response.", {
+              retryable: false,
+            });
+          } else {
+            cache.save(keys[index]!, entry.submission, job.job_id, job.expires_at);
+            return new Result(
+              index,
+              items[index]!,
+              {
+                data: status === 200 ? payload : null,
+                error: status === 200 ? null : apiError(status, payload),
+                statusCode: status,
+                requestId: job.job_id,
+                attempts: outcome.attempts,
+              },
+              (performance.now() - started) / 1000,
+              job.job_id,
+            );
+          }
+        } else if (job.state === "expired") {
+          outcome.error = new APIError("The retained batch response expired.", {
+            statusCode: 410,
+            errorCode: "job_expired",
+            requestId: entry.job_id ?? "",
+          });
+          outcome.statusCode = 410;
+        } else if (job.state === "queued" || job.state === "running") return null;
+        else outcome.error = new TransportError("Batch job returned an unknown state.", { retryable: false });
+      }
+      return new Result(
+        index,
+        items[index]!,
+        { ...outcome, data: null, requestId: entry.job_id ?? outcome.requestId },
+        (performance.now() - started) / 1000,
+        entry.job_id ?? "",
+      );
+    };
+
+    let pending = indices;
+    let polls = 0;
+    while (pending.length) {
+      await each(pending, limit, async (index) => {
+        let result = resolve(index, submissions[index]!);
+        if (!result) {
+          const entry = submissions[index]!.entry;
+          submissions[index] = { entry, outcome: await pollOnce(entry.job_id!) };
+          result = resolve(index, submissions[index]!);
+        }
+        if (result) {
+          results[index] = result;
+          options.onResult(result);
+        }
+      });
+      pending = pending.filter((index) => !results[index]);
+      if (pending.length) await sleep(backoff(++polls), options.signal);
+    }
+    return results;
+  } finally {
+    cache.close();
+  }
+}

package/src/cache.ts

@@ -0,0 +1,123 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import type { AnyRequest } from "./models.js";
+
+export interface CacheEntry {
+  submission: string;
+  job_id: string | null;
+  batch_key: string;
+  batch_size: number;
+}
+export const newId = (): string => randomUUID().replaceAll("-", "");
+const hash = (value: string) => createHash("sha256").update(value).digest("hex");
+
+/** Fingerprints include the key, origin, all parameters, and duplicate occurrence. */
+export function cacheKeys(items: readonly AnyRequest[], apiKey: string, baseUrl: string): string[] {
+  const identity = hash(apiKey);
+  const occurrences = new Map<string, number>();
+  return items.map((item) => {
+    const params = item.queryParams();
+    const sorted = Object.fromEntries(
+      Object.keys(params)
+        .sort()
+        .map((key) => [key, params[key]]),
+    );
+    const canonical = JSON.stringify([identity, baseUrl, item.path, sorted]);
+    const occurrence = occurrences.get(canonical) ?? 0;
+    occurrences.set(canonical, occurrence + 1);
+    return hash(`${canonical}:${occurrence}`);
+  });
+}
+
+/** SQLite FULL commits persist the entire workload before its first POST. */
+export class JobCache {
+  readonly path: string;
+  private readonly db: DatabaseSync;
+
+  constructor(path?: string) {
+    this.path = resolve(
+      path || process.env.LITESCRAPE_JOB_CACHE || join(homedir(), ".cache", "litescrape", "jobs-ts.sqlite3"),
+    );
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    this.db = new DatabaseSync(this.path);
+    try {
+      if (process.platform !== "win32") chmodSync(this.path, 0o600);
+      this.db.exec(`PRAGMA busy_timeout=30000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
+        CREATE TABLE IF NOT EXISTS jobs (
+          cache_key TEXT PRIMARY KEY, submission TEXT NOT NULL, job_id TEXT,
+          expires_at TEXT, updated_at REAL NOT NULL
+        );`);
+      this.transaction(() => {
+        const columns = this.db
+          .prepare("PRAGMA table_info(jobs)")
+          .all()
+          .map((row) => row.name);
+        if (!columns.includes("batch_key")) this.db.exec("ALTER TABLE jobs ADD COLUMN batch_key TEXT");
+        if (!columns.includes("batch_size")) this.db.exec("ALTER TABLE jobs ADD COLUMN batch_size INTEGER");
+      });
+    } catch (error) {
+      this.db.close();
+      throw error;
+    }
+  }
+
+  private transaction<T>(operation: () => T): T {
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const result = operation();
+      this.db.exec("COMMIT");
+      return result;
+    } catch (error) {
+      this.db.exec("ROLLBACK");
+      throw error;
+    }
+  }
+
+  prepareMany(keys: readonly string[], useCache: boolean, batchKey: string, batchSize: number): CacheEntry[] {
+    return this.transaction(() =>
+      keys.map((key) => {
+        const row = this.db
+          .prepare("SELECT submission,job_id,batch_key,batch_size FROM jobs WHERE cache_key=?")
+          .get(key);
+        if (useCache && row) {
+          if (!row.batch_key) {
+            row.batch_key = batchKey;
+            row.batch_size = batchSize;
+            this.db
+              .prepare("UPDATE jobs SET batch_key=?,batch_size=? WHERE cache_key=?")
+              .run(batchKey, batchSize, key);
+          }
+          return row as unknown as CacheEntry;
+        }
+        const entry: CacheEntry = {
+          submission: newId(),
+          job_id: null,
+          batch_key: batchKey,
+          batch_size: batchSize,
+        };
+        this.db
+          .prepare(
+            `INSERT INTO jobs(cache_key,submission,updated_at,batch_key,batch_size) VALUES (?,?,?,?,?)
+        ON CONFLICT(cache_key) DO UPDATE SET submission=excluded.submission,job_id=NULL,expires_at=NULL,
+          updated_at=excluded.updated_at,batch_key=excluded.batch_key,batch_size=excluded.batch_size`,
+          )
+          .run(key, entry.submission, Date.now() / 1000, batchKey, batchSize);
+        return entry;
+      }),
+    );
+  }
+
+  save(key: string, submission: string, jobId: string, expiresAt?: unknown): void {
+    // A concurrent fresh run can replace a slot; its submission must not be overwritten.
+    this.db
+      .prepare("UPDATE jobs SET job_id=?,expires_at=?,updated_at=? WHERE cache_key=? AND submission=?")
+      .run(jobId, typeof expiresAt === "string" ? expiresAt : null, Date.now() / 1000, key, submission);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}