@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/dataforseo-labs-client.d.ts

@@ -0,0 +1,296 @@
+/**
+ * 🧪 DataForSEO Labs client
+ *
+ * Typed access to the DataForSEO Labs API (Google database): domain visibility
+ * metrics, ranked keywords, keyword research (suggestions / ideas / related),
+ * search intent, keyword difficulty, categories and competitor research.
+ *
+ * Every method validates the API payload with Zod before returning, so callers
+ * never touch `unknown` rows. Rows that no longer match the schema are dropped
+ * instead of poisoning the result set.
+ *
+ * ```ts
+ * const labs = new DataForSeoLabsClient({ apiKey: process.env.DATAFORSEO_API_KEY });
+ * const overview = await labs.domainRankOverview({ target: "example.com" });
+ * ```
+ */
+import { z } from "zod";
+import { DataForSeoTransport, type DataForSeoTransportOptions } from "./dataforseo-transport";
+export interface DataForSeoLabsClientOptions extends DataForSeoTransportOptions {
+    /** Reuse an existing transport (and its credentials) across clients. */
+    transport?: DataForSeoTransport;
+}
+/** Geo scoping shared by every Labs endpoint. */
+export interface LabsGeoInput {
+    /** DataForSEO location code (e.g. 2840 for the United States). */
+    locationCode?: number;
+    /** DataForSEO language code (e.g. "en"). */
+    languageCode?: string;
+}
+/** A keyword row (ideas, suggestions, related keywords). */
+export declare const labsKeywordItemSchema: z.ZodObject<{
+    keyword: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    keyword_data: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        keyword: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        keyword_info: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            cpc: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            competition: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            competition_type: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            search_volume_trend: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$loose>>>;
+        keyword_properties: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            keyword_difficulty: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            search_intent_info: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                main_intent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                sub_intents: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+            }, z.core.$loose>>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type LabsKeywordItem = z.infer<typeof labsKeywordItemSchema>;
+/** A ranked keyword of a target domain. */
+export declare const labsRankedKeywordItemSchema: z.ZodObject<{
+    keyword: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    keyword_data: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        keyword: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        keyword_info: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            cpc: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            competition: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            competition_type: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            search_volume_trend: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$loose>>>;
+        keyword_properties: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            keyword_difficulty: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            search_intent_info: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                main_intent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                sub_intents: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+            }, z.core.$loose>>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+    ranked_serp_element: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        serp_item: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            relative_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            domain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            rank_group: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            rank_absolute: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            etv: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$loose>>>;
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        relative_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        rank_group: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        rank_absolute: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        etv: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type LabsRankedKeywordItem = z.infer<typeof labsRankedKeywordItemSchema>;
+/** Visibility metrics of a target domain. */
+export declare const labsDomainRankOverviewItemSchema: z.ZodObject<{
+    target: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    location_code: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    language_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metrics: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        organic: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_1: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_2_3: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_4_10: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_11_20: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_21_50: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_51_100: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            etv: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            estimated_paid_traffic_cost: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$loose>>>;
+        paid: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_1: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_2_3: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_4_10: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_11_20: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_21_50: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_51_100: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            etv: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            estimated_paid_traffic_cost: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type LabsDomainRankOverviewItem = z.infer<typeof labsDomainRankOverviewItemSchema>;
+/** A search-intent row. */
+export declare const labsSearchIntentItemSchema: z.ZodObject<{
+    keyword: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    intent: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        main_intent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        sub_intents: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    }, z.core.$loose>>>;
+    keyword_intent: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        main_intent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        sub_intents: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type LabsSearchIntentItem = z.infer<typeof labsSearchIntentItemSchema>;
+/** A bulk keyword-difficulty row. */
+export declare const labsBulkKeywordDifficultyItemSchema: z.ZodObject<{
+    keyword: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    keyword_difficulty: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$loose>;
+export type LabsBulkKeywordDifficultyItem = z.infer<typeof labsBulkKeywordDifficultyItemSchema>;
+/** A category attached to a keyword. */
+export declare const labsCategoryItemSchema: z.ZodObject<{
+    keyword: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    category_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    category_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    category_path: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    category_seo_title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type LabsCategoryItem = z.infer<typeof labsCategoryItemSchema>;
+/** A competitor row (domain intersection / competitors domain). */
+export declare const labsCompetitorItemSchema: z.ZodObject<{
+    domain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    target: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    intersections: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    avg_position: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    full_domain_metrics: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        organic: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_1: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_2_3: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_4_10: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_11_20: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_21_50: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_51_100: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            etv: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            estimated_paid_traffic_cost: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$loose>>>;
+        paid: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_1: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_2_3: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_4_10: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_11_20: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_21_50: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            pos_51_100: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            etv: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            estimated_paid_traffic_cost: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type LabsCompetitorItem = z.infer<typeof labsCompetitorItemSchema>;
+/** A SERP competitor row. */
+export declare const labsSerpCompetitorItemSchema: z.ZodObject<{
+    domain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    avg_position: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    intersections: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    serp_item: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        relative_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        domain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        rank_group: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        rank_absolute: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        etv: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type LabsSerpCompetitorItem = z.infer<typeof labsSerpCompetitorItemSchema>;
+export interface LabsPage<TItem> {
+    items: TItem[];
+    /** `total_count` reported by DataForSEO, when available. */
+    totalCount: number | null;
+}
+export interface LabsDomainRankOverviewInput extends LabsGeoInput {
+    /** Domain or URL to analyse. */
+    target: string;
+}
+export interface LabsRankedKeywordsInput extends LabsGeoInput {
+    target: string;
+    limit?: number;
+    offset?: number;
+    orderBy?: string[];
+    filters?: unknown[];
+    itemTypes?: string[];
+}
+export interface LabsRelatedKeywordsInput extends LabsGeoInput {
+    keyword: string;
+    limit?: number;
+    depth?: number;
+    includeClickstreamData?: boolean;
+}
+export interface LabsKeywordSuggestionsInput extends LabsGeoInput {
+    keyword: string;
+    limit?: number;
+    includeClickstreamData?: boolean;
+}
+export interface LabsKeywordIdeasInput extends LabsGeoInput {
+    keywords: string[];
+    limit?: number;
+    includeClickstreamData?: boolean;
+}
+export interface LabsSearchIntentInput {
+    keywords: string[];
+}
+export interface LabsBulkKeywordDifficultyInput {
+    keywords: string[];
+    locationCode?: number;
+    languageCode?: string;
+}
+export interface LabsCategoriesForKeywordsInput extends LabsGeoInput {
+    keywords: string[];
+}
+export interface LabsDomainIntersectionInput extends LabsGeoInput {
+    target1: string;
+    target2: string;
+    limit?: number;
+    orderBy?: string[];
+    filters?: unknown[];
+}
+export interface LabsCompetitorsDomainInput extends LabsGeoInput {
+    target: string;
+    limit?: number;
+    excludeTopDomains?: boolean;
+    orderBy?: string[];
+    filters?: unknown[];
+}
+export interface LabsSerpCompetitorsInput extends LabsGeoInput {
+    keywords: string[];
+    limit?: number;
+    orderBy?: string[];
+    filters?: unknown[];
+}
+/**
+ * Client for the DataForSEO Labs API. All methods are billed DataForSEO calls
+ * except {@link DataForSeoLabsClient.locationsAndLanguages}, which is free.
+ */
+export declare class DataForSeoLabsClient {
+    readonly transport: DataForSeoTransport;
+    constructor(options?: DataForSeoLabsClientOptions);
+    /** Visibility metrics of a domain (organic + paid). */
+    domainRankOverview(input: LabsDomainRankOverviewInput): Promise<LabsDomainRankOverviewItem[]>;
+    /** Keywords a domain ranks for, with positions and estimated traffic. */
+    rankedKeywords(input: LabsRankedKeywordsInput): Promise<LabsPage<LabsRankedKeywordItem>>;
+    /** Keywords semantically related to a seed keyword. */
+    relatedKeywords(input: LabsRelatedKeywordsInput): Promise<LabsKeywordItem[]>;
+    /** Google autocomplete-style suggestions for a seed keyword. */
+    keywordSuggestions(input: LabsKeywordSuggestionsInput): Promise<LabsKeywordItem[]>;
+    /** Keyword ideas (broad match + closely related variants). */
+    keywordIdeas(input: LabsKeywordIdeasInput): Promise<LabsKeywordItem[]>;
+    /** Search intent (informational / commercial / transactional, …). */
+    searchIntent(input: LabsSearchIntentInput): Promise<LabsSearchIntentItem[]>;
+    /** Keyword difficulty for a batch of keywords. */
+    bulkKeywordDifficulty(input: LabsBulkKeywordDifficultyInput): Promise<LabsBulkKeywordDifficultyItem[]>;
+    /** Category taxonomy attached to a batch of keywords. */
+    categoriesForKeywords(input: LabsCategoriesForKeywordsInput): Promise<LabsCategoryItem[]>;
+    /** Keywords shared by two domains (or shared by one domain and a keyword). */
+    domainIntersection(input: LabsDomainIntersectionInput): Promise<LabsCompetitorItem[]>;
+    /** Organic competitors of a target domain. */
+    competitorsDomain(input: LabsCompetitorsDomainInput): Promise<LabsCompetitorItem[]>;
+    /** Domains competing for a set of keywords. */
+    serpCompetitors(input: LabsSerpCompetitorsInput): Promise<LabsSerpCompetitorItem[]>;
+    /** Free list of the locations and languages supported by Labs. */
+    locationsAndLanguages(): Promise<unknown>;
+    private parseRows;
+}
+/** Convenience factory for {@link DataForSeoLabsClient}. */
+export declare function createDataForSeoLabsClient(options?: DataForSeoLabsClientOptions): DataForSeoLabsClient;

package/dist/dataforseo-llm-mentions-client.d.ts

@@ -0,0 +1,213 @@
+/**
+ * 💬 DataForSEO LLM Mentions client
+ *
+ * Typed access to the AI Optimization LLM Mentions API: where a brand (or a
+ * domain, or a keyword) shows up in AI answers, how often, and which pages
+ * and domains the answers cite.
+ *
+ * Two generations of endpoints are covered:
+ *  - the current ones (`search_mentions`, `target_metrics`,
+ *    `multi_target_metrics`, `top_mentioned_pages`, `top_mentioned_domains`);
+ *  - the legacy aliases still in use by existing integrations (`search`,
+ *    `aggregated_metrics`, `top_pages`, `cross_aggregated_metrics`).
+ *
+ * ```ts
+ * const mentions = new DataForSeoLlmMentionsClient({ apiKey });
+ * const rows = await mentions.searchMentions({
+ *   target: { domain: "example.com" },
+ *   platform: "chat_gpt",
+ *   locationCode: 2840,
+ *   languageCode: "en",
+ * });
+ * ```
+ */
+import { z } from "zod";
+import { DataForSeoTransport, type DataForSeoTransportOptions } from "./dataforseo-transport";
+export interface DataForSeoLlmMentionsClientOptions extends DataForSeoTransportOptions {
+    /** Reuse an existing transport (and its credentials) across clients. */
+    transport?: DataForSeoTransport;
+}
+/** ChatGPT mention data is only available for the US / English per DataForSEO. */
+export declare const CHATGPT_LOCATION_CODE = 2840;
+export declare const CHATGPT_LANGUAGE_CODE = "en";
+/** AI platform the mentions belong to. */
+export type LlmMentionsPlatform = "chat_gpt" | "google";
+/**
+ * DataForSEO's LLM-mentions `target` array accepts a domain OR a keyword
+ * entry. Exactly one target is sent per call.
+ */
+export type LlmMentionsTarget = {
+    domain: string;
+    includeSubdomains?: boolean;
+    searchFilter?: "include" | "exclude";
+    searchScope?: string[];
+} | {
+    keyword: string;
+    searchFilter?: "include" | "exclude";
+    searchScope?: string[];
+    matchType?: "word_match" | "partial_match";
+};
+/** Builds the wire shape of a mentions target. */
+export declare function buildLlmMentionsTarget(input: {
+    type: "domain" | "keyword";
+    value: string;
+    includeSubdomains?: boolean;
+}): LlmMentionsTarget;
+/** One AI answer that mentioned the target. */
+export declare const llmMentionItemSchema: z.ZodObject<{
+    question: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    sources: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        domain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>>>;
+    ai_search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    monthly_searches: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        year: z.ZodNumber;
+        month: z.ZodNumber;
+        search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$loose>>>>;
+    first_response_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    last_response_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    brand_entities: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>>>;
+}, z.core.$loose>;
+export type LlmMentionItem = z.infer<typeof llmMentionItemSchema>;
+/** Aggregated mention metrics of a target. */
+export declare const llmAggregatedTotalSchema: z.ZodObject<{
+    platform: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mentions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        ai_search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        impressions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$loose>>>>;
+}, z.core.$loose>;
+export type LlmAggregatedTotal = z.infer<typeof llmAggregatedTotalSchema>;
+/** Metrics of a single target (current `target_metrics` endpoint). */
+export declare const llmTargetMetricsSchema: z.ZodObject<{
+    mentions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    impressions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    ai_search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    platform: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mentions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        ai_search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        impressions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$loose>>>>;
+}, z.core.$loose>;
+export type LlmTargetMetrics = z.infer<typeof llmTargetMetricsSchema>;
+/** A page cited by the AI answers. */
+export declare const llmTopPageItemSchema: z.ZodObject<{
+    key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    platform: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mentions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        ai_search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        impressions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$loose>>>>;
+}, z.core.$loose>;
+export type LlmTopPageItem = z.infer<typeof llmTopPageItemSchema>;
+/** A domain cited by the AI answers. */
+export declare const llmTopDomainItemSchema: z.ZodObject<{
+    key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    domain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    platform: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mentions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        ai_search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        impressions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$loose>>>>;
+}, z.core.$loose>;
+export type LlmTopDomainItem = z.infer<typeof llmTopDomainItemSchema>;
+/** One row of the cross-aggregated comparison (key = aggregation label). */
+export declare const llmCrossAggregatedItemSchema: z.ZodObject<{
+    key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    platform: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mentions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        ai_search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        impressions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$loose>>>>;
+}, z.core.$loose>;
+export type LlmCrossAggregatedItem = z.infer<typeof llmCrossAggregatedItemSchema>;
+export interface LlmMentionsGeoInput {
+    locationCode?: number;
+    languageCode?: string;
+    /** Maximum rows to return (1..1000). */
+    limit?: number;
+    /** How many grouped elements to include per metric (1..20). */
+    internalListLimit?: number;
+    /** How many items to include per grouped metric (1..10). */
+    itemsListLimit?: number;
+}
+export interface LlmMentionsSearchInput extends LlmMentionsGeoInput {
+    target: LlmMentionsTarget;
+    platform: LlmMentionsPlatform;
+}
+export interface LlmMentionsTargetMetricsInput extends LlmMentionsGeoInput {
+    target: LlmMentionsTarget;
+    platform: LlmMentionsPlatform;
+}
+export interface LlmMentionsMultiTargetInput extends LlmMentionsGeoInput {
+    /** 2..10 aggregation groups (target + competitors). */
+    groups: Array<{
+        key: string;
+        target: LlmMentionsTarget;
+    }>;
+    platform: LlmMentionsPlatform;
+}
+export interface LlmMentionsTopPagesInput extends LlmMentionsGeoInput {
+    target: LlmMentionsTarget;
+    platform: LlmMentionsPlatform;
+    /** "sources" reads the pages the answers cite. */
+    linksScope?: "sources" | "targets";
+}
+export interface LlmMentionsTopDomainsInput extends LlmMentionsGeoInput {
+    target: LlmMentionsTarget;
+    platform: LlmMentionsPlatform;
+}
+export interface LlmMentionsCrossAggregatedInput extends LlmMentionsGeoInput {
+    groups: Array<{
+        key: string;
+        target: LlmMentionsTarget;
+    }>;
+    platform: LlmMentionsPlatform;
+}
+/**
+ * Client for the DataForSEO AI Optimization LLM Mentions API.
+ */
+export declare class DataForSeoLlmMentionsClient {
+    readonly transport: DataForSeoTransport;
+    constructor(options?: DataForSeoLlmMentionsClientOptions);
+    /** AI answers that mention the target (current `search_mentions` endpoint). */
+    searchMentions(input: LlmMentionsSearchInput): Promise<LlmMentionItem[]>;
+    /**
+     * AI answers that mention the target, through the legacy `search` endpoint.
+     * Same payload, older path — kept for integrations already wired to it.
+     */
+    searchMentionsLegacy(input: LlmMentionsSearchInput): Promise<LlmMentionItem[]>;
+    /** Mention metrics of a single target. */
+    targetMetrics(input: LlmMentionsTargetMetricsInput): Promise<LlmTargetMetrics>;
+    /** Mention metrics of 2..10 targets, one row per aggregation group. */
+    multiTargetMetrics(input: LlmMentionsMultiTargetInput): Promise<LlmCrossAggregatedItem[]>;
+    /** Pages cited by the AI answers. */
+    topMentionedPages(input: LlmMentionsTopPagesInput): Promise<LlmTopPageItem[]>;
+    /** Domains cited by the AI answers. */
+    topMentionedDomains(input: LlmMentionsTopDomainsInput): Promise<LlmTopDomainItem[]>;
+    /** Legacy aggregated metrics endpoint (`aggregated_metrics`). */
+    aggregatedMetrics(input: LlmMentionsTargetMetricsInput): Promise<LlmAggregatedTotal>;
+    /** Legacy top pages endpoint (`top_pages`). */
+    topPages(input: LlmMentionsTopPagesInput): Promise<LlmTopPageItem[]>;
+    /** Legacy cross-aggregated comparison (`cross_aggregated_metrics`). */
+    crossAggregatedMetrics(input: LlmMentionsCrossAggregatedInput): Promise<LlmCrossAggregatedItem[]>;
+    /** Free list of the locations and languages supported by LLM Mentions. */
+    locationsAndLanguages(): Promise<unknown>;
+}
+/** Convenience factory for {@link DataForSeoLlmMentionsClient}. */
+export declare function createDataForSeoLlmMentionsClient(options?: DataForSeoLlmMentionsClientOptions): DataForSeoLlmMentionsClient;

package/dist/dataforseo-transport.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 🔐 DataForSEO shared transport
+ *
+ * Authenticated HTTP + task-envelope handling shared by the five DataForSEO
+ * clients (Labs, Business, Google Ads, LLM Mentions, AI Tracking).
+ *
+ * DataForSEO v3 answers every POST with the same envelope:
+ *
+ * ```json
+ * { "status_code": 20000, "status_message": "Ok.", "cost": 0.02,
+ *   "tasks": [{ "id": "…", "status_code": 20000, "cost": 0.02, "result": [] }] }
+ * ```
+ *
+ * HTTP 200 does not mean success: a task-level `status_code >= 40000` is a
+ * failure, and 40501 "No Search Results" is a *billed but valid* empty
+ * result. This module is the single place where that distinction is enforced
+ * so the clients only map `result` into their own typed shapes.
+ *
+ * The transport never logs or embeds credentials in an error message.
+ */
+export declare const DATAFORSEO_BASE_URL = "https://api.dataforseo.com/v3";
+/** DataForSEO task status code for "No Search Results" (a billed empty result). */
+export declare const DATAFORSEO_NO_RESULTS_STATUS_CODE = 40501;
+export interface DataForSeoTransportOptions {
+    /** DataForSEO account login (https://app.dataforseo.com/api-access). */
+    login?: string;
+    /** DataForSEO account password. Combined with `login` into a Basic credential. */
+    password?: string;
+    /**
+     * Pre-encoded credential: either the base64 of `login:password` (the value
+     * stored in `DATAFORSEO_API_KEY`) or a full `Basic <token>` header value.
+     */
+    apiKey?: string;
+    /** API root, without the `/v3` suffix. */
+    baseUrl?: string;
+    /** Injected fetch implementation (tests, custom runtimes). */
+    fetchImpl?: typeof globalThis.fetch;
+    /** Per-request timeout in milliseconds. Defaults to 60s. */
+    timeoutMs?: number;
+    /** Retries for transient 5xx on idempotent GET reads. Defaults to 2. */
+    maxRetries?: number;
+}
+export type DataForSeoErrorKind = "configuration" | "http" | "task" | "parse" | "network";
+export interface DataForSeoErrorDetails {
+    kind: DataForSeoErrorKind;
+    path: string;
+    httpStatus?: number | null;
+    statusCode?: number | null;
+    costUsd?: number;
+    /** True when DataForSEO reported a charge for the failed call. */
+    charged?: boolean;
+    cause?: unknown;
+}
+/**
+ * Every failure raised by the DataForSEO clients. `charged` tells the caller
+ * whether the failed call was still billed, which decides if the failure can
+ * be surfaced as a free validation error.
+ */
+export declare class DataForSeoError extends Error {
+    readonly kind: DataForSeoErrorKind;
+    readonly path: string;
+    readonly httpStatus: number | null;
+    readonly statusCode: number | null;
+    readonly costUsd: number;
+    readonly charged: boolean;
+    constructor(message: string, details: DataForSeoErrorDetails);
+}
+/** Outcome of a single DataForSEO task. */
+export interface DataForSeoTaskOutcome {
+    /** Task id, when DataForSEO returned one. */
+    id: string | null;
+    /** Task-level status code (20000 on success). */
+    statusCode: number;
+    statusMessage: string;
+    /** Cost reported by DataForSEO for the task, in USD. */
+    costUsd: number;
+    /** True when DataForSEO billed the call (cost > 0). */
+    charged: boolean;
+    /**
+     * `task.result` verbatim. The shape depends on the API family: Labs wraps
+     * rows in `result[0].items`, keywords_data returns the rows directly in
+     * `result`, and business_data rows live in `result[0].items` too.
+     */
+    result: unknown;
+    /** Envelope-level cost, used when the task omits its own cost field. */
+    envelopeCostUsd: number;
+}
+export interface DataForSeoTaskOptions {
+    /**
+     * Treat 40501 "No Search Results" as an empty success instead of an error.
+     * DataForSEO still bills those calls, so the caller must keep the charge.
+     */
+    treatNoResultsAsEmpty?: boolean;
+}
+/**
+ * Resolves the `Authorization` header from explicit options, falling back to
+ * the environment (`DATAFORSEO_API_KEY`, then `DATAFORSEO_USERNAME` /
+ * `DATAFORSEO_PASSWORD`). Returns undefined when no credential is available.
+ */
+export declare function resolveDataForSeoAuthorization(options?: Pick<DataForSeoTransportOptions, "login" | "password" | "apiKey">): string | undefined;
+/**
+ * Reads the rows of a Labs/business style result entry: `result[0].items`.
+ * Returns an empty array when the payload does not follow that shape.
+ */
+export declare function readItems(result: unknown): unknown[];
+/**
+ * Reads the object carried by the first result entry of a task. The metrics
+ * endpoints nest their payload under `total`; endpoints returning the payload
+ * directly are handled as a fallback.
+ */
+export declare function readResultObject(result: unknown): Record<string, unknown> | null;
+/**
+ * Reads the `result` array of a GET envelope (locations, categories, models).
+ * Falls back to the payload itself when it already is an array.
+ */
+export declare function readEnvelopeResult(payload: unknown): unknown[];
+/**
+ * Reads the first result entry of a task (`task.result[0]`) as a record. Used
+ * by the endpoints whose payload is a single object (business tasks, target
+ * metrics) instead of a list of rows.
+ */
+export declare function readFirstResultEntry(result: unknown): Record<string, unknown> | null;
+/**
+ * Reads the rows of a keywords_data style result: the rows sit directly in
+ * `task.result`.
+ */
+export declare function readDirectItems(result: unknown): unknown[];
+/** Reads `result[0].total_count` when present. */
+export declare function readTotalCount(result: unknown): number | null;
+/**
+ * Authenticated DataForSEO v3 transport. One instance can be shared by every
+ * DataForSEO client so credentials and the HTTP policy live in one place.
+ */
+export declare class DataForSeoTransport {
+    private readonly authorization;
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    constructor(options?: DataForSeoTransportOptions);
+    /** True when a credential is available. */
+    get configured(): boolean;
+    /** Absolute URL for an API path such as `dataforseo_labs/google/…/live`. */
+    url(path: string): string;
+    /** GET helper for free read-only endpoints (locations, categories, models). */
+    get<T = unknown>(path: string): Promise<T>;
+    /** POST helper returning the raw envelope. */
+    post<T = unknown>(path: string, body: unknown): Promise<T>;
+    /**
+     * POSTs a task, validates the envelope and returns the task outcome.
+     * Throws a {@link DataForSeoError} of kind `task` when the task failed.
+     */
+    runTask(path: string, body: unknown, options?: DataForSeoTaskOptions): Promise<DataForSeoTaskOutcome>;
+    private readJson;
+    private send;
+}