litescrape-sdk 0.1.0

package/dist/esm/runtime.js

@@ -0,0 +1,226 @@
+import { createHash } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { APIError, TransportError, apiError, isObject } from "./errors.js";
+import { VERSION } from "./version.js";
+export const DEFAULT_BASE_URL = "https://api.litescrape.com";
+export const USER_AGENT = `litescrape-sdk/${VERSION} (Node/${process.versions.node}; ${process.platform}; TypeScript)`;
+export const CLIENT_HEADER_VALUE = `typescript-sdk/${VERSION}`;
+export const emptyOutcome = () => ({
+    data: null,
+    error: null,
+    statusCode: null,
+    requestId: "",
+    attempts: 0,
+});
+/** FIFO gate. Waiting and backoff do not hold a network slot. */
+export class Semaphore {
+    limit;
+    active = 0;
+    queue = [];
+    constructor(limit) {
+        this.limit = limit;
+    }
+    async acquire(signal) {
+        signal?.throwIfAborted();
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                start: () => {
+                    signal?.removeEventListener("abort", waiter.cancel);
+                    this.active++;
+                    let released = false;
+                    resolve(() => {
+                        if (released)
+                            return;
+                        released = true;
+                        this.active--;
+                        this.drain();
+                    });
+                },
+                cancel: () => {
+                    const index = this.queue.indexOf(waiter);
+                    if (index !== -1)
+                        this.queue.splice(index, 1);
+                    reject(signal?.reason);
+                },
+            };
+            if (this.active < this.limit)
+                waiter.start();
+            else {
+                this.queue.push(waiter);
+                signal?.addEventListener("abort", waiter.cancel, { once: true });
+            }
+        });
+    }
+    resize(limit) {
+        this.limit = limit;
+        this.drain();
+    }
+    drain() {
+        while (this.active < this.limit && this.queue.length)
+            this.queue.shift().start();
+    }
+}
+// One key-wide cap shared by overlapping scrape calls. Per-call limits are separate,
+// so two callers with different overrides cannot accidentally multiply the key limit.
+const sharedLimits = new Map();
+export function keySemaphore(key, baseUrl, limit) {
+    const identity = createHash("sha256")
+        .update(JSON.stringify([key, baseUrl]))
+        .digest("hex");
+    let entry = sharedLimits.get(identity);
+    if (!entry) {
+        entry = { semaphore: new Semaphore(limit), users: 0 };
+        sharedLimits.set(identity, entry);
+    }
+    else
+        entry.semaphore.resize(limit);
+    entry.users++;
+    const held = entry;
+    return {
+        semaphore: held.semaphore,
+        release: () => {
+            held.users--;
+            if (held.users === 0)
+                sharedLimits.delete(identity);
+        },
+    };
+}
+export function shouldRetry(error) {
+    if (error instanceof TransportError)
+        return error.retryable;
+    return (error instanceof APIError &&
+        (error.retryable ||
+            error.statusCode === 429 ||
+            (error.statusCode ?? 0) >= 500 ||
+            ["proxy_capacity_unavailable", "upstream_session_unavailable", "service_unavailable"].includes(error.errorCode)));
+}
+export function backoff(attempt, retryAfter = null) {
+    if (retryAfter !== null)
+        return Math.min(Math.max(retryAfter, 0), 30);
+    const ceiling = Math.min(30, 2 ** Math.min(Math.max(attempt - 1, 0), 6));
+    return ceiling * (0.5 + Math.random() / 2);
+}
+export async function sleep(seconds, signal) {
+    signal?.throwIfAborted();
+    try {
+        await delay(seconds * 1000, undefined, { signal });
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        throw error;
+    }
+}
+export async function requestWithRetries(path, options) {
+    const { signal } = options;
+    const outcome = emptyOutcome();
+    for (let attempt = 1; attempt <= options.attempts; attempt++) {
+        signal?.throwIfAborted();
+        const release = [];
+        try {
+            for (const semaphore of options.semaphores ?? [])
+                release.push(await semaphore.acquire(signal));
+            signal?.throwIfAborted();
+            const blocked = options.gate?.();
+            if (blocked) {
+                outcome.error = blocked;
+                outcome.statusCode = blocked.statusCode;
+                outcome.requestId = blocked.requestId;
+                return outcome;
+            }
+            Object.assign(outcome, emptyOutcome(), { attempts: attempt });
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(new DOMException("HTTP transport timed out", "TimeoutError")), options.timeout * 1000);
+            const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+            try {
+                const url = new URL(options.baseUrl + path);
+                for (const [key, value] of Object.entries(options.params ?? {}))
+                    url.searchParams.set(key, value);
+                const response = await options.fetch(url, {
+                    method: options.method ?? "GET",
+                    redirect: "manual",
+                    signal: combined,
+                    headers: {
+                        Accept: "application/json",
+                        "User-Agent": USER_AGENT,
+                        "X-Litescrape-Client": CLIENT_HEADER_VALUE,
+                        Authorization: `Bearer ${options.apiKey}`,
+                        ...(options.body ? { "Content-Type": "application/json" } : {}),
+                        ...options.headers,
+                    },
+                    ...(options.body ? { body: JSON.stringify(options.body) } : {}),
+                });
+                outcome.statusCode = response.status;
+                outcome.requestId = response.headers.get("x-request-id") ?? "";
+                let data;
+                let bodyError;
+                try {
+                    data = await response.json();
+                }
+                catch (error) {
+                    bodyError = error;
+                }
+                signal?.throwIfAborted();
+                if (!(options.acceptedStatuses ?? [200]).includes(response.status)) {
+                    outcome.error = apiError(response.status, data, response.headers);
+                    outcome.requestId = outcome.error instanceof APIError ? outcome.error.requestId : outcome.requestId;
+                }
+                else if (bodyError) {
+                    outcome.error = new TransportError("Response body was not JSON", {
+                        retryable: true,
+                        cause: bodyError,
+                    });
+                }
+                else if (!isObject(data)) {
+                    outcome.error = new TransportError("Response body was not a JSON object", { retryable: true });
+                }
+                else
+                    outcome.data = data;
+            }
+            catch (cause) {
+                signal?.throwIfAborted();
+                const retryable = controller.signal.aborted ||
+                    cause instanceof TypeError ||
+                    (cause instanceof DOMException && ["AbortError", "TimeoutError"].includes(cause.name));
+                outcome.error = new TransportError(cause instanceof Error ? cause.message : String(cause), {
+                    retryable,
+                    cause,
+                });
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+            // Set the fatal gate while the slot is held, before queued requests can start.
+            options.onOutcome?.(outcome);
+        }
+        finally {
+            for (const unlock of release.reverse())
+                unlock();
+        }
+        if (!outcome.error || attempt === options.attempts || !shouldRetry(outcome.error))
+            return outcome;
+        await sleep(backoff(attempt, outcome.error instanceof APIError ? outcome.error.retryAfter : null), signal);
+    }
+    return outcome;
+}
+/** A bounded worker pool; errors stop new work and settle all workers before returning. */
+export async function each(items, limit, operation) {
+    let next = 0;
+    let failed = false;
+    const worker = async () => {
+        while (!failed && next < items.length) {
+            const item = items[next++];
+            try {
+                await operation(item);
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+        }
+    };
+    const settled = await Promise.allSettled(Array.from({ length: Math.min(limit, items.length) }, worker));
+    const failure = settled.find((result) => result.status === "rejected");
+    if (failure?.status === "rejected")
+        throw failure.reason;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/esm/runtime.js.map

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

package/dist/esm/stores.d.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { type Rule } from "./validation.js";
+export declare const playApps: {
+    hl: z.ZodDefault<z.ZodString>;
+    gl: z.ZodDefault<z.ZodString>;
+    q: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    chart: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    next_page_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    section_page_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    see_more_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    apps_category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    age: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        AGE_RANGE1: "AGE_RANGE1";
+        AGE_RANGE2: "AGE_RANGE2";
+        AGE_RANGE3: "AGE_RANGE3";
+    }>>>;
+    store_device: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        car: "car";
+        chromebook: "chromebook";
+        phone: "phone";
+        tablet: "tablet";
+        tv: "tv";
+        watch: "watch";
+    }>>>;
+};
+export declare const playGames: {
+    hl: z.ZodDefault<z.ZodString>;
+    gl: z.ZodDefault<z.ZodString>;
+    q: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    chart: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    next_page_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    section_page_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    see_more_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    games_category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    store_device: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        chromebook: "chromebook";
+        phone: "phone";
+        tablet: "tablet";
+        tv: "tv";
+        watch: "watch";
+        windows: "windows";
+    }>>>;
+};
+export declare const playBooks: {
+    hl: z.ZodDefault<z.ZodString>;
+    gl: z.ZodDefault<z.ZodString>;
+    q: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    chart: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    next_page_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    section_page_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    see_more_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    books_category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    age: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        AGE_RANGE1: "AGE_RANGE1";
+        AGE_RANGE2: "AGE_RANGE2";
+        AGE_RANGE3: "AGE_RANGE3";
+    }>>>;
+    price: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>, z.ZodNumber>>>;
+};
+export declare const playMovies: {
+    hl: z.ZodDefault<z.ZodString>;
+    gl: z.ZodDefault<z.ZodString>;
+    q: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    chart: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    next_page_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    section_page_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    see_more_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    movies_category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    age: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        AGE_RANGE1: "AGE_RANGE1";
+        AGE_RANGE2: "AGE_RANGE2";
+        AGE_RANGE3: "AGE_RANGE3";
+    }>>>;
+};
+export declare const playProduct: {
+    hl: z.ZodDefault<z.ZodString>;
+    gl: z.ZodDefault<z.ZodString>;
+    product_id: z.ZodString;
+    store: z.ZodDefault<z.ZodEnum<{
+        apps: "apps";
+        audiobooks: "audiobooks";
+        books: "books";
+        movies: "movies";
+        tv: "tv";
+    }>>;
+    season_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+export declare const playReviews: {
+    hl: z.ZodDefault<z.ZodString>;
+    gl: z.ZodDefault<z.ZodString>;
+    product_id: z.ZodString;
+    store: z.ZodDefault<z.ZodEnum<{
+        apps: "apps";
+        audiobooks: "audiobooks";
+        books: "books";
+        movies: "movies";
+        tv: "tv";
+    }>>;
+    platform: z.ZodDefault<z.ZodEnum<{
+        chromebook: "chromebook";
+        phone: "phone";
+        tablet: "tablet";
+        tv: "tv";
+        watch: "watch";
+    }>>;
+    rating: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>, z.ZodNumber>>>;
+    sort_by: z.ZodDefault<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>, z.ZodNumber>>;
+    num: z.ZodDefault<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>, z.ZodNumber>>;
+    next_page_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+export declare const playRules: (operation: string) => Rule[];
+export declare const appleSearch: {
+    country: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    term: z.ZodString;
+    lang: z.ZodDefault<z.ZodString>;
+    num: z.ZodDefault<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>, z.ZodNumber>>;
+    disallow_explicit: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
+        false: "false";
+        true: "true";
+    }>]>, z.ZodTransform<boolean, "false" | "true" | boolean>>>;
+    property: z.ZodOptional<z.ZodNullable<z.ZodLiteral<"developer">>>;
+    category_id: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>, z.ZodNumber>>>;
+    device: z.ZodDefault<z.ZodEnum<{
+        desktop: "desktop";
+        mobile: "mobile";
+        tablet: "tablet";
+    }>>;
+};
+export declare const appleProduct: {
+    country: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    product_id: z.ZodString;
+    type: z.ZodDefault<z.ZodLiteral<"app">>;
+};
+export declare const appleReviews: {
+    country: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    product_id: z.ZodString;
+    sort: z.ZodDefault<z.ZodEnum<{
+        mosthelpful: "mosthelpful";
+        mostrecent: "mostrecent";
+    }>>;
+    page: z.ZodDefault<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>, z.ZodNumber>>;
+};
+//# sourceMappingURL=stores.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../../src/stores.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAA+B,KAAK,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAuDzE,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;CAKpB,CAAC;AACF,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;CAIrB,CAAC;AACF,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;CAKrB,CAAC;AACF,eAAO,MAAM,UAAU;;;;;;;;;;;;;;CAAgE,CAAC;AACxF,eAAO,MAAM,WAAW;;;;;;;;;;;;CAA+E,CAAC;AACxG,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;CASvB,CAAC;AAGF,eAAO,MAAM,SAAS,cAAe,MAAM,KAAG,IAAI,EAsDjD,CAAC;AAoBF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;CA4BvB,CAAC;AACF,eAAO,MAAM,YAAY;;;;CAAmF,CAAC;AAC7G,eAAO,MAAM,YAAY;;;;;;;;CAYxB,CAAC"}

package/dist/esm/stores.js

@@ -0,0 +1,190 @@
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import { isObject } from "./errors.js";
+import { optional as opt, has, issue } from "./validation.js";
+const cleanText = z
+    .string()
+    .refine((value) => !/[\x00-\x1f\x7f]/.test(value), "Control characters are not allowed")
+    .refine((value) => !Array.from(value).some((c) => c.length === 1 && /[\ud800-\udfff]/.test(c)), "Use valid Unicode text");
+const query = cleanText
+    .refine((value) => Buffer.byteLength(value.trim(), "utf8") <= 2048, "Use at most 2,048 UTF-8 bytes")
+    .trim()
+    .min(1)
+    .max(2048);
+const whole = z
+    .union([
+    z.number().int(),
+    cleanText
+        .trim()
+        .regex(/^[+-]?\d+$/)
+        .transform(Number),
+])
+    .pipe(z.number().int());
+const category = cleanText
+    .min(1)
+    .max(128)
+    .regex(/^[a-zA-Z0-9_-]+$/);
+const identifier = cleanText
+    .min(1)
+    .max(512)
+    .regex(/^[a-zA-Z0-9_.-]+$/);
+const token = cleanText
+    .min(1)
+    .max(65536)
+    .regex(/^[a-zA-Z0-9_=+/:.-]+$/);
+const age = z.enum(["AGE_RANGE1", "AGE_RANGE2", "AGE_RANGE3"]);
+const store = z.enum(["apps", "books", "audiobooks", "movies", "tv"]).default("apps");
+const playLocale = {
+    hl: cleanText
+        .max(32)
+        .regex(/^[a-zA-Z]{2,3}(?:[-_][a-zA-Z0-9]{2,8}){0,3}$/)
+        .default("en"),
+    gl: cleanText
+        .regex(/^[a-zA-Z]{2}$/)
+        .toLowerCase()
+        .default("us"),
+};
+const listing = {
+    ...playLocale,
+    q: opt(query),
+    chart: opt(category),
+    next_page_token: opt(token),
+    section_page_token: opt(token),
+    see_more_token: opt(token),
+};
+export const playApps = {
+    ...listing,
+    apps_category: opt(category),
+    age: opt(age),
+    store_device: opt(z.enum(["phone", "tablet", "tv", "chromebook", "watch", "car"])),
+};
+export const playGames = {
+    ...listing,
+    games_category: opt(category),
+    store_device: opt(z.enum(["phone", "tablet", "tv", "chromebook", "watch", "windows"])),
+};
+export const playBooks = {
+    ...listing,
+    books_category: opt(category),
+    age: opt(age),
+    price: opt(whole.pipe(z.number().min(1).max(2))),
+};
+export const playMovies = { ...listing, movies_category: opt(category), age: opt(age) };
+export const playProduct = { ...playLocale, product_id: identifier, store, season_id: opt(identifier) };
+export const playReviews = {
+    ...playLocale,
+    product_id: identifier,
+    store,
+    platform: z.enum(["phone", "tablet", "watch", "chromebook", "tv"]).default("phone"),
+    rating: opt(whole.pipe(z.number().min(1).max(5))),
+    sort_by: whole.pipe(z.number().min(1).max(3)).default(1),
+    num: whole.pipe(z.number().min(1).max(199)).default(40),
+    next_page_token: opt(token),
+};
+const tokenFields = ["next_page_token", "section_page_token", "see_more_token"];
+export const playRules = (operation) => [
+    (p, c) => {
+        if (["apps", "games", "books", "movies"].includes(operation)) {
+            if ([...tokenFields, "chart"].filter((f) => p[f]).length > 1)
+                issue(c, "chart and pagination selectors are mutually exclusive");
+            if (p.chart && p.q)
+                issue(c, "chart and q are mutually exclusive");
+            if (p.chart && has(p, "store_device") && p.store_device !== "phone")
+                issue(c, "Device-specific storefronts do not support charts; omit chart or use phone");
+            const categoryValue = p[`${operation}_category`];
+            if (p.q && categoryValue)
+                issue(c, "q and category are mutually exclusive");
+            if (has(p, "store_device") && (p.q || categoryValue))
+                issue(c, "store_device excludes q and category");
+            if (p.age && categoryValue !== (operation === "books" ? "coll_1689" : "FAMILY"))
+                issue(c, "age requires the children's category");
+            if (has(p, "price") && !p.q)
+                issue(c, "price requires q");
+        }
+        if (p.season_id && p.store !== "tv")
+            issue(c, "season_id requires store=tv");
+        const context = Object.fromEntries(Object.entries(p).filter(([key, value]) => value != null && ![...tokenFields, "chart"].includes(key)));
+        if (["apps", "games"].includes(operation) && !p.q && !p[`${operation}_category`])
+            context.store_device ??= "phone";
+        for (const field of tokenFields) {
+            const encoded = p[field];
+            if (typeof encoded !== "string")
+                continue;
+            const kind = field === "next_page_token"
+                ? operation === "reviews"
+                    ? "reviews"
+                    : "page"
+                : field === "section_page_token"
+                    ? "section"
+                    : "collection";
+            try {
+                if (!/^[a-zA-Z0-9+/_-]*={0,2}$/.test(encoded) || encoded.replace(/=+$/, "").length % 4 === 1)
+                    throw new Error();
+                const decoded = JSON.parse(new TextDecoder("utf8", { fatal: true }).decode(Buffer.from(encoded, "base64url")));
+                if (!isObject(decoded) ||
+                    decoded.v !== 1 ||
+                    decoded.operation !== operation ||
+                    decoded.kind !== kind ||
+                    !isDeepStrictEqual(decoded.context, context) ||
+                    typeof decoded.token !== "string" ||
+                    !/^[a-zA-Z0-9_=+/:.-]{1,12000}$/.test(decoded.token))
+                    throw new Error();
+            }
+            catch {
+                issue(c, "Use a returned token with the same operation and search parameters", [field]);
+            }
+        }
+    },
+];
+const storefronts = new Set("ae af ag ai al am ao ar at au az ba bb be bf bg bh bj bm bn bo br bs bt bw by bz ca cd cg ch ci cl cm cn co cr cv cy cz de dk dm do dz ec ee eg es fi fj fm fr ga gb gd ge gh gm gr gt gw gy hk hn hr hu id ie il in iq is it jm jo jp ke kg kh kn kr kw ky kz la lb lc lk lr lt lu lv ly ma md me mg mk ml mm mn mo mr ms mt mu mv mw mx my mz na ne ng ni nl no np nr nz om pa pe pg ph pk pl pt pw py qa ro rs ru rw sa sb sc se sg si sk sl sn sr st sv sz tc td th tj tm tn to tr tt tw tz ua ug us uy uz vc ve vg vn vu xk ye za zm zw".split(" "));
+const appleLocale = {
+    country: cleanText
+        .regex(/^[a-zA-Z]{2}$/)
+        .toLowerCase()
+        .transform((value) => (value === "uk" ? "gb" : value))
+        .refine((value) => storefronts.has(value), "Choose a supported Apple storefront country")
+        .default("us"),
+};
+const productId = cleanText.regex(/^[1-9][0-9]{0,19}$/);
+const quotePlus = (value) => encodeURIComponent(value)
+    .replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+    .replace(/%20/g, "+");
+export const appleSearch = {
+    ...appleLocale,
+    term: query.refine((value) => {
+        try {
+            return quotePlus(value).length <= 4096;
+        }
+        catch {
+            return false;
+        }
+    }, "Use at most 4,096 URL-encoded bytes"),
+    lang: cleanText
+        .regex(/^[a-zA-Z]{2,3}-[a-zA-Z]{2}$/)
+        .toLowerCase()
+        .default("en-us"),
+    num: whole.pipe(z.number().min(1).max(200)).default(10),
+    disallow_explicit: z
+        .union([z.boolean(), z.enum(["true", "false"])])
+        .transform((value) => value === true || value === "true")
+        .default(false),
+    property: opt(z.literal("developer")),
+    category_id: opt(whole.pipe(z
+        .number()
+        .min(1)
+        .max(2 ** 31 - 1))),
+    device: z.enum(["mobile", "tablet", "desktop"]).default("mobile"),
+};
+export const appleProduct = { ...appleLocale, product_id: productId, type: z.literal("app").default("app") };
+export const appleReviews = {
+    ...appleLocale,
+    product_id: productId,
+    sort: z.enum(["mostrecent", "mosthelpful"]).default("mostrecent"),
+    page: whole
+        .pipe(z
+        .number()
+        .min(1)
+        .max(2 ** 31 - 1))
+        .default(1),
+};
+//# sourceMappingURL=stores.js.map

package/dist/esm/stores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.js","sourceRoot":"","sources":["../../src/stores.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,QAAQ,IAAI,GAAG,EAAE,GAAG,EAAE,KAAK,EAAa,MAAM,iBAAiB,CAAC;AAEzE,MAAM,SAAS,GAAG,CAAC;KAChB,MAAM,EAAE;KACR,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,oCAAoC,CAAC;KACvF,MAAM,CACL,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EACtF,wBAAwB,CACzB,CAAC;AACJ,MAAM,KAAK,GAAG,SAAS;KACpB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE,+BAA+B,CAAC;KACnG,IAAI,EAAE;KACN,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,IAAI,CAAC,CAAC;AACb,MAAM,KAAK,GAAG,CAAC;KACZ,KAAK,CAAC;IACL,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAChB,SAAS;SACN,IAAI,EAAE;SACN,KAAK,CAAC,YAAY,CAAC;SACnB,SAAS,CAAC,MAAM,CAAC;CACrB,CAAC;KACD,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;AAC1B,MAAM,QAAQ,GAAG,SAAS;KACvB,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,KAAK,CAAC,kBAAkB,CAAC,CAAC;AAC7B,MAAM,UAAU,GAAG,SAAS;KACzB,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,KAAK,CAAC,mBAAmB,CAAC,CAAC;AAC9B,MAAM,KAAK,GAAG,SAAS;KACpB,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,KAAK,CAAC;KACV,KAAK,CAAC,uBAAuB,CAAC,CAAC;AAClC,MAAM,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;AAC/D,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AACtF,MAAM,UAAU,GAAG;IACjB,EAAE,EAAE,SAAS;SACV,GAAG,CAAC,EAAE,CAAC;SACP,KAAK,CAAC,8CAA8C,CAAC;SACrD,OAAO,CAAC,IAAI,CAAC;IAChB,EAAE,EAAE,SAAS;SACV,KAAK,CAAC,eAAe,CAAC;SACtB,WAAW,EAAE;SACb,OAAO,CAAC,IAAI,CAAC;CACjB,CAAC;AACF,MAAM,OAAO,GAAG;IACd,GAAG,UAAU;IACb,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC;IACb,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC;IACpB,eAAe,EAAE,GAAG,CAAC,KAAK,CAAC;IAC3B,kBAAkB,EAAE,GAAG,CAAC,KAAK,CAAC;IAC9B,cAAc,EAAE,GAAG,CAAC,KAAK,CAAC;CAC3B,CAAC;AACF,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,GAAG,OAAO;IACV,aAAa,EAAE,GAAG,CAAC,QAAQ,CAAC;IAC5B,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC;IACb,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;CACnF,CAAC;AACF,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,GAAG,OAAO;IACV,cAAc,EAAE,GAAG,CAAC,QAAQ,CAAC;IAC7B,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;CACvF,CAAC;AACF,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,GAAG,OAAO;IACV,cAAc,EAAE,GAAG,CAAC,QAAQ,CAAC;IAC7B,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC;IACb,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;CACjD,CAAC;AACF,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,GAAG,OAAO,EAAE,eAAe,EAAE,GAAG,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;AACxF,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,GAAG,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;AACxG,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,GAAG,UAAU;IACb,UAAU,EAAE,UAAU;IACtB,KAAK;IACL,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACnF,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACvD,eAAe,EAAE,GAAG,CAAC,KAAK,CAAC;CAC5B,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,gBAAgB,CAAC,CAAC;AAChF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,SAAiB,EAAU,EAAE,CAAC;IACtD,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACP,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7D,IAAI,CAAC,GAAG,WAAW,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC;gBAC1D,KAAK,CAAC,CAAC,EAAE,uDAAuD,CAAC,CAAC;YACpE,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;gBAAE,KAAK,CAAC,CAAC,EAAE,oCAAoC,CAAC,CAAC;YACnE,IAAI,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,YAAY,KAAK,OAAO;gBACjE,KAAK,CAAC,CAAC,EAAE,4EAA4E,CAAC,CAAC;YACzF,MAAM,aAAa,GAAG,CAAC,CAAC,GAAG,SAAS,WAAW,CAAC,CAAC;YACjD,IAAI,CAAC,CAAC,CAAC,IAAI,aAAa;gBAAE,KAAK,CAAC,CAAC,EAAE,uCAAuC,CAAC,CAAC;YAC5E,IAAI,GAAG,CAAC,CAAC,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC;gBAAE,KAAK,CAAC,CAAC,EAAE,sCAAsC,CAAC,CAAC;YACvG,IAAI,CAAC,CAAC,GAAG,IAAI,aAAa,KAAK,CAAC,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC;gBAC7E,KAAK,CAAC,CAAC,EAAE,sCAAsC,CAAC,CAAC;YACnD,IAAI,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAAE,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI;YAAE,KAAK,CAAC,CAAC,EAAE,6BAA6B,CAAC,CAAC;QAE7E,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,CAChC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,CAAC,GAAG,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CACtG,CAAC;QACF,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,WAAW,CAAC;YAC9E,OAAO,CAAC,YAAY,KAAK,OAAO,CAAC;QACnC,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;YAChC,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;YACzB,IAAI,OAAO,OAAO,KAAK,QAAQ;gBAAE,SAAS;YAC1C,MAAM,IAAI,GACR,KAAK,KAAK,iBAAiB;gBACzB,CAAC,CAAC,SAAS,KAAK,SAAS;oBACvB,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,MAAM;gBACV,CAAC,CAAC,KAAK,KAAK,oBAAoB;oBAC9B,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,YAAY,CAAC;YACrB,IAAI,CAAC;gBACH,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC;oBAC1F,MAAM,IAAI,KAAK,EAAE,CAAC;gBACpB,MAAM,OAAO,GAAY,IAAI,CAAC,KAAK,CACjC,IAAI,WAAW,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CACnF,CAAC;gBACF,IACE,CAAC,QAAQ,CAAC,OAAO,CAAC;oBAClB,OAAO,CAAC,CAAC,KAAK,CAAC;oBACf,OAAO,CAAC,SAAS,KAAK,SAAS;oBAC/B,OAAO,CAAC,IAAI,KAAK,IAAI;oBACrB,CAAC,iBAAiB,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC;oBAC5C,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ;oBACjC,CAAC,+BAA+B,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;oBAEpD,MAAM,IAAI,KAAK,EAAE,CAAC;YACtB,CAAC;YAAC,MAAM,CAAC;gBACP,KAAK,CAAC,CAAC,EAAE,oEAAoE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;YAC1F,CAAC;QACH,CAAC;IACH,CAAC;CACF,CAAC;AAEF,MAAM,WAAW,GAAG,IAAI,GAAG,CACzB,8gBAA8gB,CAAC,KAAK,CAClhB,GAAG,CACJ,CACF,CAAC;AACF,MAAM,WAAW,GAAG;IAClB,OAAO,EAAE,SAAS;SACf,KAAK,CAAC,eAAe,CAAC;SACtB,WAAW,EAAE;SACb,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;SACrD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,6CAA6C,CAAC;SACxF,OAAO,CAAC,IAAI,CAAC;CACjB,CAAC;AACF,MAAM,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;AACxD,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,EAAE,CAClC,kBAAkB,CAAC,KAAK,CAAC;KACtB,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;KAC5E,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC1B,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,GAAG,WAAW;IACd,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAC3B,IAAI,CAAC;YACH,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC,EAAE,qCAAqC,CAAC;IACzC,IAAI,EAAE,SAAS;SACZ,KAAK,CAAC,6BAA6B,CAAC;SACpC,WAAW,EAAE;SACb,OAAO,CAAC,OAAO,CAAC;IACnB,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACvD,iBAAiB,EAAE,CAAC;SACjB,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;SAC/C,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,MAAM,CAAC;SACxD,OAAO,CAAC,KAAK,CAAC;IACjB,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACrC,WAAW,EAAE,GAAG,CACd,KAAK,CAAC,IAAI,CACR,CAAC;SACE,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CACpB,CACF;IACD,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;CAClE,CAAC;AACF,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,GAAG,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;AAC7G,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,GAAG,WAAW;IACd,UAAU,EAAE,SAAS;IACrB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;IACjE,IAAI,EAAE,KAAK;SACR,IAAI,CACH,CAAC;SACE,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CACpB;SACA,OAAO,CAAC,CAAC,CAAC;CACd,CAAC"}

package/dist/esm/validation.d.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+export declare const optional: <S extends z.ZodType>(schema: S) => z.ZodOptional<z.ZodNullable<S>>;
+export declare const text: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBigInt]>, z.ZodTransform<string, string | number | bigint>>;
+export declare const number: z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodPipe<z.ZodBoolean, z.ZodTransform<number, boolean>>]>, z.ZodNumber>;
+export declare const integer: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodPipe<z.ZodBoolean, z.ZodTransform<number, boolean>>]>, z.ZodNumber>, z.ZodNumber>;
+export declare const boolean: z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodPipe<z.ZodString, z.ZodEnum<{
+    0: "0";
+    1: "1";
+    f: "f";
+    false: "false";
+    n: "n";
+    no: "no";
+    off: "off";
+    on: "on";
+    t: "t";
+    true: "true";
+    y: "y";
+    yes: "yes";
+}>>]>, z.ZodTransform<boolean, "0" | "1" | "f" | "false" | "n" | "no" | "off" | "on" | "t" | "true" | "y" | "yes" | 0 | 1 | boolean>>;
+export declare const flag: z.ZodPipe<z.ZodUnion<readonly [z.ZodEnum<{
+    0: "0";
+    1: "1";
+}>, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodBoolean]>, z.ZodTransform<"0" | "1", "0" | "1" | 0 | 1 | boolean>>;
+export declare const strictBoolean: z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
+    false: "false";
+    true: "true";
+}>]>;
+export declare const timeoutSeconds: z.ZodNumber;
+export declare const device: z.ZodEnum<{
+    desktop: "desktop";
+    mobile: "mobile";
+    tablet: "tablet";
+}>;
+type Params = Record<string, unknown>;
+export type Rule = (params: Params, context: z.RefinementCtx) => void;
+export declare const issue: (context: z.RefinementCtx, message: string, path?: string[]) => void;
+export declare const has: (params: Params, field: string) => boolean;
+export declare const requireAny: (...fields: string[]) => Rule;
+export declare const exactlyOne: (...fields: string[]) => Rule;
+export declare const atMostOne: (...fields: string[]) => Rule;
+export declare const paired: (a: string, b: string) => Rule;
+export declare const requires: (field: string, dependency: string) => Rule;
+/** Validated, immutable request. Construct an endpoint class or pass a plain object to scrape. */
+export declare class ScrapeRequest<E extends string = string> {
+    #private;
+    readonly endpoint: E;
+    readonly timeout?: number | null;
+    constructor(path: string, params: object & {
+        endpoint: E;
+    }, prototype?: object);
+    get path(): string;
+    queryParams(): Record<string, string>;
+    query_params(): Record<string, string>;
+    /** Copy a validated request with a default deadline without revalidating its cursor context. */
+    withTimeout(timeout: number): this;
+}
+export interface RequestClass<E extends string, Input, Output> {
+    new (params: Input): ScrapeRequest<E> & Readonly<Output>;
+    readonly endpoint: E;
+    readonly path: string;
+    readonly parameters: readonly string[];
+}
+export declare function defineRequest<E extends string, Shape extends z.ZodRawShape>(endpoint: E, path: string, shape: Shape, rules?: Rule[]): RequestClass<E, z.input<z.ZodObject<Shape>>, z.output<z.ZodObject<Shape>>>;
+export {};
+//# sourceMappingURL=validation.d.ts.map