@opensite/hooks 0.1.1 → 2.0.2

package/dist/core/useWebsiteExtractorBase.d.ts

@@ -0,0 +1,9 @@
+import { type WebsiteExtractorOptions, type WebsiteExtractorResult, type WebsiteExtractMeta } from "./websiteExtractorTypes.js";
+interface UseWebsiteExtractorBaseConfig<TResponse extends WebsiteExtractMeta, TData> {
+    endpoint: string;
+    options: WebsiteExtractorOptions;
+    selectData: (payload: Omit<TResponse, keyof WebsiteExtractMeta>, raw: TResponse, meta: WebsiteExtractMeta) => TData;
+    shouldSkip?: (url: string) => boolean;
+}
+export declare function useWebsiteExtractorBase<TResponse extends WebsiteExtractMeta, TData>(config: UseWebsiteExtractorBaseConfig<TResponse, TData>): WebsiteExtractorResult<TData, TResponse>;
+export {};

package/dist/core/useWebsiteExtractorBase.js

@@ -0,0 +1,153 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useDebounceCallback } from "./useDebounceCallback.js";
+import { useDebounceValue } from "./useDebounceValue.js";
+import { useIsClient } from "./useIsClient.js";
+import { useMap } from "./useMap.js";
+import { fetchWebsiteExtractor } from "./websiteExtractorService.js";
+import { DEFAULT_EXTRACTOR_CACHE, DEFAULT_EXTRACTOR_DEBOUNCE_MS, DEFAULT_EXTRACTOR_ENABLED, DEFAULT_EXTRACTOR_REFRESH_DEBOUNCE_MS, DEFAULT_WEBSITE_EXTRACTOR_BASE_URL, extractWebsiteMeta, stripWebsiteMeta, } from "./websiteExtractorTypes.js";
+export function useWebsiteExtractorBase(config) {
+    const { endpoint, options, selectData, shouldSkip } = config;
+    const isClient = useIsClient();
+    const [state, setState] = useState({
+        loading: false,
+    });
+    const [, cacheActions] = useMap();
+    const cacheEnabled = options.cache ?? DEFAULT_EXTRACTOR_CACHE;
+    const enabled = options.enabled ?? DEFAULT_EXTRACTOR_ENABLED;
+    const debounceMs = options.debounceMs ?? DEFAULT_EXTRACTOR_DEBOUNCE_MS;
+    const refreshDebounceMs = options.refreshDebounceMs ?? DEFAULT_EXTRACTOR_REFRESH_DEBOUNCE_MS;
+    const normalizedUrl = useMemo(() => {
+        return options.url?.trim() ?? "";
+    }, [options.url]);
+    const debouncedUrl = useDebounceValue(normalizedUrl, debounceMs);
+    const refreshCounterRef = useRef(0);
+    const lastRefreshHandledRef = useRef(0);
+    const [refreshToken, setRefreshToken] = useState(0);
+    const { debouncedCallback: scheduleRefresh, cancel: cancelRefresh } = useDebounceCallback(() => {
+        refreshCounterRef.current += 1;
+        setRefreshToken(refreshCounterRef.current);
+    }, refreshDebounceMs);
+    const refresh = useCallback(() => {
+        scheduleRefresh();
+    }, [scheduleRefresh]);
+    useEffect(() => () => cancelRefresh(), [cancelRefresh]);
+    const requestKey = useMemo(() => {
+        if (!debouncedUrl) {
+            return "";
+        }
+        const baseUrl = options.baseUrl ?? DEFAULT_WEBSITE_EXTRACTOR_BASE_URL;
+        const apiKey = options.apiKey ?? "";
+        return `${endpoint}:${baseUrl}:${apiKey}:${debouncedUrl}`;
+    }, [
+        endpoint,
+        options.apiKey,
+        options.baseUrl,
+        debouncedUrl,
+    ]);
+    const inFlightControllerRef = useRef(null);
+    useEffect(() => {
+        if (!isClient) {
+            return;
+        }
+        if (!enabled || !debouncedUrl) {
+            setState({ loading: false });
+            return;
+        }
+        if (shouldSkip?.(debouncedUrl)) {
+            setState({ loading: false });
+            return;
+        }
+        const forceRefresh = refreshToken !== lastRefreshHandledRef.current;
+        if (forceRefresh) {
+            lastRefreshHandledRef.current = refreshToken;
+        }
+        if (cacheEnabled && !forceRefresh) {
+            const cached = cacheActions.get(requestKey);
+            if (cached) {
+                setState({
+                    loading: false,
+                    data: cached.data,
+                    raw: cached.raw,
+                    meta: cached.meta,
+                });
+                return;
+            }
+        }
+        inFlightControllerRef.current?.abort();
+        const controller = new AbortController();
+        inFlightControllerRef.current = controller;
+        setState((prev) => ({
+            ...prev,
+            loading: true,
+            error: undefined,
+        }));
+        fetchWebsiteExtractor({
+            endpoint,
+            url: debouncedUrl,
+            apiKey: options.apiKey,
+            baseUrl: options.baseUrl,
+            signal: controller.signal,
+        })
+            .then((result) => {
+            if (controller.signal.aborted) {
+                return;
+            }
+            if (!result.ok) {
+                setState((prev) => ({
+                    ...prev,
+                    loading: false,
+                    error: result.error,
+                }));
+                return;
+            }
+            const raw = result.response;
+            const meta = extractWebsiteMeta(raw);
+            const payload = stripWebsiteMeta(raw);
+            const data = selectData(payload, raw, meta);
+            if (cacheEnabled) {
+                cacheActions.set(requestKey, { data, raw, meta });
+            }
+            setState({
+                loading: false,
+                data,
+                raw,
+                meta,
+            });
+        })
+            .catch((error) => {
+            if (controller.signal.aborted) {
+                return;
+            }
+            setState((prev) => ({
+                ...prev,
+                loading: false,
+                error: {
+                    message: error instanceof Error
+                        ? error.message
+                        : "Request failed unexpectedly.",
+                    raw: error,
+                },
+            }));
+        });
+        return () => {
+            controller.abort();
+        };
+    }, [
+        cacheActions,
+        cacheEnabled,
+        debouncedUrl,
+        enabled,
+        endpoint,
+        isClient,
+        options.apiKey,
+        options.baseUrl,
+        requestKey,
+        refreshToken,
+        selectData,
+        shouldSkip,
+    ]);
+    return useMemo(() => ({
+        ...state,
+        refresh,
+    }), [refresh, state]);
+}

package/dist/core/useWebsiteLinksExtractor.cjs

@@ -0,0 +1,16 @@
+import { useCallback } from "react";
+import { useWebsiteExtractorBase } from "./useWebsiteExtractorBase.js";
+export function useWebsiteLinksExtractor(options) {
+    const selectData = useCallback((payload) => {
+        return {
+            totalLinks: payload.totalLinks ?? 0,
+            uniqueDomains: payload.uniqueDomains ?? 0,
+            links: payload.links ?? [],
+        };
+    }, []);
+    return useWebsiteExtractorBase({
+        endpoint: "links",
+        options,
+        selectData,
+    });
+}

package/dist/core/useWebsiteLinksExtractor.d.ts

@@ -0,0 +1,14 @@
+import type { WebsiteExtractorOptions, WebsiteExtractorResponse, WebsiteExtractorResult } from "./websiteExtractorTypes.js";
+export interface WebsiteLinkRecord {
+    url: string;
+    text: string;
+    isExternal: boolean;
+    domain?: string | null;
+}
+export interface WebsiteLinksPayload {
+    totalLinks: number;
+    uniqueDomains: number;
+    links: WebsiteLinkRecord[];
+}
+export type WebsiteLinksResponse = WebsiteExtractorResponse<WebsiteLinksPayload>;
+export declare function useWebsiteLinksExtractor(options: WebsiteExtractorOptions): WebsiteExtractorResult<WebsiteLinksPayload, WebsiteLinksResponse>;

package/dist/core/useWebsiteLinksExtractor.js

@@ -0,0 +1,16 @@
+import { useCallback } from "react";
+import { useWebsiteExtractorBase } from "./useWebsiteExtractorBase.js";
+export function useWebsiteLinksExtractor(options) {
+    const selectData = useCallback((payload) => {
+        return {
+            totalLinks: payload.totalLinks ?? 0,
+            uniqueDomains: payload.uniqueDomains ?? 0,
+            links: payload.links ?? [],
+        };
+    }, []);
+    return useWebsiteExtractorBase({
+        endpoint: "links",
+        options,
+        selectData,
+    });
+}

package/dist/core/useWebsiteMetaExtractor.cjs

@@ -0,0 +1,20 @@
+import { useCallback } from "react";
+import { useWebsiteExtractorBase } from "./useWebsiteExtractorBase.js";
+export function useWebsiteMetaExtractor(options) {
+    const selectData = useCallback((payload) => {
+        return {
+            title: payload.title ?? undefined,
+            description: payload.description ?? undefined,
+            language: payload.language ?? undefined,
+            canonicalUrl: payload.canonicalUrl ?? undefined,
+            feedUrl: payload.feedUrl ?? null,
+            textContentLength: payload.textContentLength ?? undefined,
+            metaTags: payload.metaTags ?? {},
+        };
+    }, []);
+    return useWebsiteExtractorBase({
+        endpoint: "meta",
+        options,
+        selectData,
+    });
+}

package/dist/core/useWebsiteMetaExtractor.d.ts

@@ -0,0 +1,12 @@
+import type { WebsiteExtractorOptions, WebsiteExtractorResponse, WebsiteExtractorResult } from "./websiteExtractorTypes.js";
+export interface WebsiteMetaPayload {
+    title?: string | null;
+    description?: string | null;
+    language?: string | null;
+    canonicalUrl?: string | null;
+    feedUrl?: string | null;
+    textContentLength?: number | null;
+    metaTags: Record<string, string>;
+}
+export type WebsiteMetaResponse = WebsiteExtractorResponse<WebsiteMetaPayload>;
+export declare function useWebsiteMetaExtractor(options: WebsiteExtractorOptions): WebsiteExtractorResult<WebsiteMetaPayload, WebsiteMetaResponse>;

package/dist/core/useWebsiteMetaExtractor.js

@@ -0,0 +1,20 @@
+import { useCallback } from "react";
+import { useWebsiteExtractorBase } from "./useWebsiteExtractorBase.js";
+export function useWebsiteMetaExtractor(options) {
+    const selectData = useCallback((payload) => {
+        return {
+            title: payload.title ?? undefined,
+            description: payload.description ?? undefined,
+            language: payload.language ?? undefined,
+            canonicalUrl: payload.canonicalUrl ?? undefined,
+            feedUrl: payload.feedUrl ?? null,
+            textContentLength: payload.textContentLength ?? undefined,
+            metaTags: payload.metaTags ?? {},
+        };
+    }, []);
+    return useWebsiteExtractorBase({
+        endpoint: "meta",
+        options,
+        selectData,
+    });
+}

package/dist/core/useWebsiteRssExtractor.cjs

@@ -0,0 +1,15 @@
+import { useCallback } from "react";
+import { useWebsiteExtractorBase } from "./useWebsiteExtractorBase.js";
+export function useWebsiteRssExtractor(options) {
+    const selectData = useCallback((payload) => {
+        return {
+            feedUrl: payload.feedUrl ?? null,
+            feeds: payload.feeds ?? [],
+        };
+    }, []);
+    return useWebsiteExtractorBase({
+        endpoint: "rss",
+        options,
+        selectData,
+    });
+}

package/dist/core/useWebsiteRssExtractor.d.ts

@@ -0,0 +1,12 @@
+import type { WebsiteExtractorOptions, WebsiteExtractorResponse, WebsiteExtractorResult } from "./websiteExtractorTypes.js";
+export interface WebsiteRssFeed {
+    url: string;
+    feedType: string;
+    title?: string | null;
+}
+export interface WebsiteRssPayload {
+    feedUrl?: string | null;
+    feeds: WebsiteRssFeed[];
+}
+export type WebsiteRssResponse = WebsiteExtractorResponse<WebsiteRssPayload>;
+export declare function useWebsiteRssExtractor(options: WebsiteExtractorOptions): WebsiteExtractorResult<WebsiteRssPayload, WebsiteRssResponse>;

package/dist/core/useWebsiteRssExtractor.js

@@ -0,0 +1,15 @@
+import { useCallback } from "react";
+import { useWebsiteExtractorBase } from "./useWebsiteExtractorBase.js";
+export function useWebsiteRssExtractor(options) {
+    const selectData = useCallback((payload) => {
+        return {
+            feedUrl: payload.feedUrl ?? null,
+            feeds: payload.feeds ?? [],
+        };
+    }, []);
+    return useWebsiteExtractorBase({
+        endpoint: "rss",
+        options,
+        selectData,
+    });
+}

package/dist/core/useWebsiteSchemaExtractor.cjs

@@ -0,0 +1,15 @@
+import { useCallback } from "react";
+import { useWebsiteExtractorBase } from "./useWebsiteExtractorBase.js";
+export function useWebsiteSchemaExtractor(options) {
+    const selectData = useCallback((payload) => {
+        return {
+            schema: payload.schema ?? [],
+            schemaTypes: payload.schemaTypes ?? [],
+        };
+    }, []);
+    return useWebsiteExtractorBase({
+        endpoint: "schema",
+        options,
+        selectData,
+    });
+}

package/dist/core/useWebsiteSchemaExtractor.d.ts

@@ -0,0 +1,11 @@
+import type { WebsiteExtractorOptions, WebsiteExtractorResponse, WebsiteExtractorResult } from "./websiteExtractorTypes.js";
+export interface WebsiteSchemaRecord {
+    schema_type: string;
+    value: Record<string, unknown>;
+}
+export interface WebsiteSchemaPayload {
+    schema: WebsiteSchemaRecord[];
+    schemaTypes: string[];
+}
+export type WebsiteSchemaResponse = WebsiteExtractorResponse<WebsiteSchemaPayload>;
+export declare function useWebsiteSchemaExtractor(options: WebsiteExtractorOptions): WebsiteExtractorResult<WebsiteSchemaPayload, WebsiteSchemaResponse>;

package/dist/core/useWebsiteSchemaExtractor.js

@@ -0,0 +1,15 @@
+import { useCallback } from "react";
+import { useWebsiteExtractorBase } from "./useWebsiteExtractorBase.js";
+export function useWebsiteSchemaExtractor(options) {
+    const selectData = useCallback((payload) => {
+        return {
+            schema: payload.schema ?? [],
+            schemaTypes: payload.schemaTypes ?? [],
+        };
+    }, []);
+    return useWebsiteExtractorBase({
+        endpoint: "schema",
+        options,
+        selectData,
+    });
+}

package/dist/core/websiteExtractorService.cjs

@@ -0,0 +1,66 @@
+import { DEFAULT_WEBSITE_EXTRACTOR_BASE_URL, } from "./websiteExtractorTypes.js";
+const EXTRACTOR_PATH = "/api/v1/extract";
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, "");
+}
+export function buildWebsiteExtractorUrl(request) {
+    const baseUrl = normalizeBaseUrl(request.baseUrl ?? DEFAULT_WEBSITE_EXTRACTOR_BASE_URL);
+    const params = new URLSearchParams();
+    if (request.apiKey) {
+        params.set("api_key", request.apiKey);
+    }
+    params.set("url", request.url);
+    return `${baseUrl}${EXTRACTOR_PATH}/${request.endpoint}?${params.toString()}`;
+}
+export async function fetchWebsiteExtractor(request) {
+    if (!request.url || request.url.trim().length === 0) {
+        return {
+            ok: false,
+            error: {
+                message: "URL is required.",
+            },
+        };
+    }
+    const endpoint = buildWebsiteExtractorUrl(request);
+    try {
+        const response = await fetch(endpoint, {
+            method: "GET",
+            signal: request.signal,
+        });
+        let payload = null;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            payload = null;
+        }
+        if (!response.ok) {
+            const errorPayload = payload;
+            const error = {
+                message: errorPayload?.error ??
+                    `Request failed with status ${response.status}.`,
+                status: errorPayload?.status ?? response.status,
+                raw: payload,
+            };
+            return { ok: false, error };
+        }
+        return { ok: true, response: payload };
+    }
+    catch (error) {
+        if (request.signal?.aborted) {
+            return {
+                ok: false,
+                error: {
+                    message: "Request aborted.",
+                },
+            };
+        }
+        return {
+            ok: false,
+            error: {
+                message: error instanceof Error ? error.message : "Request failed unexpectedly.",
+                raw: error,
+            },
+        };
+    }
+}

package/dist/core/websiteExtractorService.d.ts

@@ -0,0 +1,3 @@
+import { type WebsiteExtractorClientResult, type WebsiteExtractorRequest } from "./websiteExtractorTypes.js";
+export declare function buildWebsiteExtractorUrl(request: WebsiteExtractorRequest): string;
+export declare function fetchWebsiteExtractor<TResponse>(request: WebsiteExtractorRequest): Promise<WebsiteExtractorClientResult<TResponse>>;

package/dist/core/websiteExtractorService.js

@@ -0,0 +1,66 @@
+import { DEFAULT_WEBSITE_EXTRACTOR_BASE_URL, } from "./websiteExtractorTypes.js";
+const EXTRACTOR_PATH = "/api/v1/extract";
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, "");
+}
+export function buildWebsiteExtractorUrl(request) {
+    const baseUrl = normalizeBaseUrl(request.baseUrl ?? DEFAULT_WEBSITE_EXTRACTOR_BASE_URL);
+    const params = new URLSearchParams();
+    if (request.apiKey) {
+        params.set("api_key", request.apiKey);
+    }
+    params.set("url", request.url);
+    return `${baseUrl}${EXTRACTOR_PATH}/${request.endpoint}?${params.toString()}`;
+}
+export async function fetchWebsiteExtractor(request) {
+    if (!request.url || request.url.trim().length === 0) {
+        return {
+            ok: false,
+            error: {
+                message: "URL is required.",
+            },
+        };
+    }
+    const endpoint = buildWebsiteExtractorUrl(request);
+    try {
+        const response = await fetch(endpoint, {
+            method: "GET",
+            signal: request.signal,
+        });
+        let payload = null;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            payload = null;
+        }
+        if (!response.ok) {
+            const errorPayload = payload;
+            const error = {
+                message: errorPayload?.error ??
+                    `Request failed with status ${response.status}.`,
+                status: errorPayload?.status ?? response.status,
+                raw: payload,
+            };
+            return { ok: false, error };
+        }
+        return { ok: true, response: payload };
+    }
+    catch (error) {
+        if (request.signal?.aborted) {
+            return {
+                ok: false,
+                error: {
+                    message: "Request aborted.",
+                },
+            };
+        }
+        return {
+            ok: false,
+            error: {
+                message: error instanceof Error ? error.message : "Request failed unexpectedly.",
+                raw: error,
+            },
+        };
+    }
+}

package/dist/core/websiteExtractorTypes.cjs

@@ -0,0 +1,25 @@
+export const DEFAULT_WEBSITE_EXTRACTOR_BASE_URL = "https://octane.buzz";
+export const DEFAULT_EXTRACTOR_DEBOUNCE_MS = 250;
+export const DEFAULT_EXTRACTOR_REFRESH_DEBOUNCE_MS = 150;
+export const DEFAULT_EXTRACTOR_ENABLED = true;
+export const DEFAULT_EXTRACTOR_CACHE = true;
+export function extractWebsiteMeta(response) {
+    const { requestedUrl, finalUrl, url, normalizedUrl, status, contentType, fetchedAt, bodyBytes, bodyTruncated, maxBodyBytes, cache, } = response;
+    return {
+        requestedUrl,
+        finalUrl,
+        url,
+        normalizedUrl,
+        status,
+        contentType,
+        fetchedAt,
+        bodyBytes,
+        bodyTruncated,
+        maxBodyBytes,
+        cache,
+    };
+}
+export function stripWebsiteMeta(response) {
+    const { requestedUrl: _requestedUrl, finalUrl: _finalUrl, url: _url, normalizedUrl: _normalizedUrl, status: _status, contentType: _contentType, fetchedAt: _fetchedAt, bodyBytes: _bodyBytes, bodyTruncated: _bodyTruncated, maxBodyBytes: _maxBodyBytes, cache: _cache, ...payload } = response;
+    return payload;
+}

package/dist/core/websiteExtractorTypes.d.ts

@@ -0,0 +1,65 @@
+export interface WebsiteExtractCacheMeta {
+    hit: boolean;
+    ageSeconds: number;
+    ttlSeconds: number;
+    staleWhileRevalidateSeconds: number;
+}
+export interface WebsiteExtractMeta {
+    requestedUrl: string;
+    finalUrl: string;
+    url: string;
+    normalizedUrl: string;
+    status: number;
+    contentType: string;
+    fetchedAt: string;
+    bodyBytes: number;
+    bodyTruncated: boolean;
+    maxBodyBytes: number;
+    cache: WebsiteExtractCacheMeta;
+}
+export interface WebsiteExtractorError {
+    message: string;
+    status?: number;
+    raw?: unknown;
+}
+export interface WebsiteExtractorOptions {
+    url?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    debounceMs?: number;
+    refreshDebounceMs?: number;
+    enabled?: boolean;
+    cache?: boolean;
+}
+export interface WebsiteExtractorState<TData, TRaw = TData> {
+    loading: boolean;
+    data?: TData;
+    raw?: TRaw;
+    meta?: WebsiteExtractMeta;
+    error?: WebsiteExtractorError;
+}
+export interface WebsiteExtractorResult<TData, TRaw = TData> extends WebsiteExtractorState<TData, TRaw> {
+    refresh: () => void;
+}
+export type WebsiteExtractorResponse<TPayload> = WebsiteExtractMeta & TPayload;
+export interface WebsiteExtractorRequest {
+    endpoint: string;
+    url: string;
+    apiKey?: string;
+    baseUrl?: string;
+    signal?: AbortSignal;
+}
+export type WebsiteExtractorClientResult<T> = {
+    ok: true;
+    response: T;
+} | {
+    ok: false;
+    error: WebsiteExtractorError;
+};
+export declare const DEFAULT_WEBSITE_EXTRACTOR_BASE_URL = "https://octane.buzz";
+export declare const DEFAULT_EXTRACTOR_DEBOUNCE_MS = 250;
+export declare const DEFAULT_EXTRACTOR_REFRESH_DEBOUNCE_MS = 150;
+export declare const DEFAULT_EXTRACTOR_ENABLED = true;
+export declare const DEFAULT_EXTRACTOR_CACHE = true;
+export declare function extractWebsiteMeta(response: WebsiteExtractMeta): WebsiteExtractMeta;
+export declare function stripWebsiteMeta<TResponse extends WebsiteExtractMeta>(response: TResponse): Omit<TResponse, keyof WebsiteExtractMeta>;

package/dist/core/websiteExtractorTypes.js

@@ -0,0 +1,25 @@
+export const DEFAULT_WEBSITE_EXTRACTOR_BASE_URL = "https://octane.buzz";
+export const DEFAULT_EXTRACTOR_DEBOUNCE_MS = 250;
+export const DEFAULT_EXTRACTOR_REFRESH_DEBOUNCE_MS = 150;
+export const DEFAULT_EXTRACTOR_ENABLED = true;
+export const DEFAULT_EXTRACTOR_CACHE = true;
+export function extractWebsiteMeta(response) {
+    const { requestedUrl, finalUrl, url, normalizedUrl, status, contentType, fetchedAt, bodyBytes, bodyTruncated, maxBodyBytes, cache, } = response;
+    return {
+        requestedUrl,
+        finalUrl,
+        url,
+        normalizedUrl,
+        status,
+        contentType,
+        fetchedAt,
+        bodyBytes,
+        bodyTruncated,
+        maxBodyBytes,
+        cache,
+    };
+}
+export function stripWebsiteMeta(response) {
+    const { requestedUrl: _requestedUrl, finalUrl: _finalUrl, url: _url, normalizedUrl: _normalizedUrl, status: _status, contentType: _contentType, fetchedAt: _fetchedAt, bodyBytes: _bodyBytes, bodyTruncated: _bodyTruncated, maxBodyBytes: _maxBodyBytes, cache: _cache, ...payload } = response;
+    return payload;
+}