@lynxflow/seo-engine 2.8.0 → 3.2.0

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

@@ -0,0 +1,191 @@
+/**
+ * 🏢 DataForSEO Business Data client
+ *
+ * Typed access to the Business Data API: business listings search, business
+ * categories, Google My Business info, questions & answers, and the queued
+ * review / profile-update tasks.
+ *
+ * The three review endpoints (reviews, extended reviews, My Business updates)
+ * are *task based*: DataForSEO charges at `task_post` and serves the rows for
+ * free at `task_get`. The client models that split explicitly so a caller
+ * never pays twice for the same data.
+ *
+ * ```ts
+ * const business = new DataForSeoBusinessClient({ apiKey });
+ * const taskId = await business.postReviewsTask({ keyword: "Café Lynx", languageCode: "fr" });
+ * const outcome = await business.getTaskResult("reviews", taskId);
+ * ```
+ */
+import { z } from "zod";
+import { DataForSeoTransport, type DataForSeoTransportOptions } from "./dataforseo-transport";
+export interface DataForSeoBusinessClientOptions extends DataForSeoTransportOptions {
+    /** Reuse an existing transport (and its credentials) across clients. */
+    transport?: DataForSeoTransport;
+}
+/**
+ * Location + language for the Google business_data endpoints. They accept
+ * either a coordinate (`"lat,lng,radius"` in meters) or a location code, never
+ * both, so the coordinate wins when present.
+ */
+export interface BusinessLocationInput {
+    /** `"latitude,longitude,radius"` in meters. */
+    locationCoordinate?: string;
+    /** DataForSEO location code. */
+    locationCode?: number;
+    /** DataForSEO language code (e.g. "en"). */
+    languageCode: string;
+}
+/** Identifies the business a task targets. */
+export interface BusinessIdentifierInput {
+    /** Business name / search keyword. */
+    keyword?: string;
+    /** Google CID. */
+    cid?: string;
+    /** Google Place ID. */
+    placeId?: string;
+}
+export declare const businessListingItemSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    domain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    place_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    cid: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    check_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    is_claimed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    rating: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    reviews_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    feature_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    location: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        latitude: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        longitude: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type BusinessListingItem = z.infer<typeof businessListingItemSchema>;
+export declare const businessCategoryRowSchema: z.ZodObject<{
+    category_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    category_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    business_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$loose>;
+export type BusinessCategoryRow = z.infer<typeof businessCategoryRowSchema>;
+export declare const businessInfoItemSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    domain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    place_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    cid: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    check_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    rating: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    reviews_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$loose>;
+export type BusinessInfoItem = z.infer<typeof businessInfoItemSchema>;
+export declare const businessQuestionItemSchema: z.ZodObject<{
+    question: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    answer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    total_answers: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    author: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type BusinessQuestionItem = z.infer<typeof businessQuestionItemSchema>;
+export declare const businessReviewItemSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    rating: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    author: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    profile_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    review_timestamp: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    review_text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type BusinessReviewItem = z.infer<typeof businessReviewItemSchema>;
+export interface BusinessListingsSearchInput {
+    /** Search keyword (business name or category). */
+    keyword?: string;
+    /** Business title filter. */
+    title?: string;
+    /** Business categories, e.g. `["Iced Coffee"]`. */
+    categories?: string[];
+    /** `"latitude,longitude,radius"` in meters. */
+    locationCoordinate?: string;
+    /** DataForSEO location code. */
+    locationCode?: number;
+    /** DataForSEO language code. */
+    languageCode: string;
+    /** Only claimed profiles. */
+    isClaimed?: boolean;
+    limit?: number;
+    offset?: number;
+    orderBy?: string[];
+    filters?: unknown[];
+}
+export interface BusinessMyBusinessInfoInput extends BusinessLocationInput {
+    keyword: string;
+}
+export interface BusinessQuestionsAndAnswersInput extends BusinessLocationInput {
+    keyword: string;
+    /** How many question rows to collect per business. */
+    depth?: number;
+}
+export interface BusinessReviewsTaskInput extends BusinessIdentifierInput, BusinessLocationInput {
+    /** How many reviews to collect. */
+    depth?: number;
+    /** Only the regular reviews endpoint supports sorting. */
+    sortBy?: string;
+}
+export interface BusinessUpdatesTaskInput extends BusinessLocationInput {
+    keyword: string;
+    depth?: number;
+}
+/** Queued business_data tasks supported by the client. */
+export type BusinessTaskEndpoint = "reviews" | "extended_reviews" | "my_business_updates";
+export interface BusinessTaskOutcome {
+    /** "pending" while DataForSEO is still collecting, "completed" otherwise. */
+    status: "pending" | "completed";
+    /** Task id echoed by DataForSEO. */
+    taskId: string | null;
+    /** Reviews / updates rows once the task completed. */
+    reviews: BusinessReviewItem[];
+    /** Raw first result entry, for callers that need untouched fields. */
+    result: Record<string, unknown> | null;
+}
+/**
+ * Client for the DataForSEO Business Data API.
+ */
+export declare class DataForSeoBusinessClient {
+    readonly transport: DataForSeoTransport;
+    constructor(options?: DataForSeoBusinessClientOptions);
+    /** Searches the Business Listings Database. */
+    searchBusinessListings(input: BusinessListingsSearchInput): Promise<BusinessListingItem[]>;
+    /** Free list of the business listing categories with their business count. */
+    fetchBusinessListingsCategories(): Promise<BusinessCategoryRow[]>;
+    /** Google My Business profile of a business, or null when there is none. */
+    fetchMyBusinessInfo(input: BusinessMyBusinessInfoInput): Promise<BusinessInfoItem | null>;
+    /** Questions & answers of a business (answered and unanswered rows). */
+    fetchQuestionsAndAnswers(input: BusinessQuestionsAndAnswersInput): Promise<BusinessQuestionItem[]>;
+    /**
+     * Queues a Google reviews collection task and returns its task id.
+     * DataForSEO bills this call.
+     */
+    postReviewsTask(input: BusinessReviewsTaskInput): Promise<string>;
+    /**
+     * Queues an extended reviews task (reviews collected from other platforms
+     * such as Yelp or Tripadvisor) and returns its task id.
+     */
+    postExtendedReviewsTask(input: BusinessReviewsTaskInput): Promise<string>;
+    /** Queues a My Business profile updates task and returns its task id. */
+    postMyBusinessUpdatesTask(input: BusinessUpdatesTaskInput): Promise<string>;
+    /**
+     * Collects a queued task. Collection is free: the task was already billed
+     * at `task_post`.
+     */
+    getTaskResult(endpoint: BusinessTaskEndpoint, taskId: string): Promise<BusinessTaskOutcome>;
+    private postTask;
+}
+/** Convenience factory for {@link DataForSeoBusinessClient}. */
+export declare function createDataForSeoBusinessClient(options?: DataForSeoBusinessClientOptions): DataForSeoBusinessClient;

package/dist/dataforseo-cost-model.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 💳 DataForSEO Cost Model & Credit Ledger
+ *
+ * Modèle de coût typé par famille d'endpoints DataForSEO (prix indicatifs en
+ * cents d'euro par appel, pay-as-you-go), wrapper priced() qui attache un
+ * devis de coût à chaque appel fetcheur, et CreditLedger (réserve / règlement
+ * / solde) pour le prépaiement et la facturation post-exécution.
+ *
+ * Barèmes à recalibrer contre la facturation DataForSEO réelle.
+ */
+export type DataForSeoEndpointFamily = "serp" | "keywordMetrics" | "backlinks" | "labs" | "business" | "googleAds" | "lighthouse" | "aiTracking" | "llmMentions";
+export interface CostQuote {
+    endpoint: string;
+    family: DataForSeoEndpointFamily;
+    estimatedCents: number;
+    currency: "EUR";
+    measured: boolean;
+}
+export interface Estimator<T> {
+    estimate(params: T): CostQuote;
+}
+export type PricedResult<T> = {
+    data: T;
+    quote: CostQuote;
+};
+/**
+ * Enveloppe un fetcher asynchrone : estime le coût avant exécution, puis
+ * retourne la donnée accompagnée de son devis. Idéal pour l'affichage
+ * "Coût estimé ~$0.XX" avant un appel API payant.
+ */
+export declare function priced<T>(fetcher: (params: T) => Promise<T>, estimator: Estimator<T>): (params: T) => Promise<PricedResult<T>>;
+declare const LABS_CENTS: Record<string, number>;
+declare const BUSINESS_CENTS: Record<string, number>;
+export interface SerpParams {
+    engine: "google" | "bing" | "yandex";
+    keyword: string;
+    locationCode: number;
+    languageCode: string;
+    depth?: number;
+}
+export interface KeywordMetricsParams {
+    keywords: string[];
+    locationCode: number;
+    languageCode: string;
+}
+export interface BacklinksParams {
+    target: string;
+    mode: "summary" | "history" | "lost_new";
+}
+export interface LabsParams {
+    tool: keyof typeof LABS_CENTS;
+    keywords: string[];
+    locationCode?: number;
+    languageCode?: string;
+}
+export interface BusinessParams {
+    endpoint: keyof typeof BUSINESS_CENTS;
+    locationCode?: number;
+    limit?: number;
+}
+export interface GoogleAdsParams {
+    keywords: string[];
+    locationCode?: number;
+}
+export interface LighthouseParams {
+    url: string;
+    strategy: "mobile" | "desktop";
+}
+export interface AiTrackingParams {
+    query: string;
+    engine: "chatgpt" | "claude" | "gemini" | "perplexity";
+}
+export interface LlmMentionsParams {
+    brand: string;
+    queries: string[];
+}
+export declare const serpEstimator: Estimator<SerpParams>;
+export declare const keywordMetricsEstimator: Estimator<KeywordMetricsParams>;
+export declare const backlinksEstimator: Estimator<BacklinksParams>;
+export declare const labsEstimator: Estimator<LabsParams>;
+export declare const businessEstimator: Estimator<BusinessParams>;
+export declare const googleAdsEstimator: Estimator<GoogleAdsParams>;
+export declare const lighthouseEstimator: Estimator<LighthouseParams>;
+export declare const aiTrackingEstimator: Estimator<AiTrackingParams>;
+export declare const llmMentionsEstimator: Estimator<LlmMentionsParams>;
+export interface CreditReservation {
+    id: string;
+    reservedCents: number;
+    settledCents: number;
+    status: "held" | "settled" | "released";
+}
+export interface CreditLedgerSnapshot {
+    availableCents: number;
+    heldCents: number;
+    totalCents: number;
+}
+export interface CreditLedgerEntry {
+    id: string;
+    type: "reserve" | "settle" | "release";
+    cents: number;
+    balanceAfter: number;
+    timestamp: string;
+}
+export declare class CreditLedger {
+    private balanceCents;
+    private reservations;
+    private entries;
+    constructor(initialCents?: number);
+    /**
+     * Bloque un montant sur le solde disponible (pré-autorisation).
+     * Retourne une réservation à régler ultérieurement via settle().
+     */
+    reserve(cents: number, idempotencyKey?: string): CreditReservation;
+    /**
+     * Transforme une réservation en frais réels. Le reliquat non consommé est
+     * rendu au solde disponible.
+     */
+    settle(reservationId: string, actualCents: number): CreditReservation;
+    /**
+     * Annule une réservation non encore réglée et rend les fonds au solde.
+     */
+    release(reservationId: string): CreditReservation;
+    balance(): CreditLedgerSnapshot;
+    history(): readonly CreditLedgerEntry[];
+}
+export {};

package/dist/dataforseo-google-ads-client.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 💰 DataForSEO Google Ads (Keywords Data) client
+ *
+ * Typed access to the `keywords_data/google_ads` endpoints: search volume,
+ * keyword suggestions for a keyword or a site, and ad traffic estimates.
+ *
+ * Google Ads data covers every geotarget Google Ads supports, which is why it
+ * is the fallback for the countries the Labs database does not cover. Ads
+ * rows carry volume, CPC and competition but no keyword difficulty and no
+ * search intent.
+ *
+ * ```ts
+ * const ads = new DataForSeoGoogleAdsClient({ apiKey });
+ * const volumes = await ads.searchVolume({ keywords: ["seo audit"], locationCode: 2840, languageCode: "en" });
+ * ```
+ */
+import { z } from "zod";
+import { DataForSeoTransport, type DataForSeoTransportOptions } from "./dataforseo-transport";
+export interface DataForSeoGoogleAdsClientOptions extends DataForSeoTransportOptions {
+    /** Reuse an existing transport (and its credentials) across clients. */
+    transport?: DataForSeoTransport;
+}
+/** A Google Ads keyword metric row. */
+export declare const adsKeywordItemSchema: z.ZodObject<{
+    keyword: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    location_code: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    language_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    search_partners: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    competition: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    competition_type: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cpc: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cpc_currency: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    search_volume_trend: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$loose>;
+export type AdsKeywordItem = z.infer<typeof adsKeywordItemSchema>;
+/** A Google Ads traffic estimation row. */
+export declare const adsTrafficItemSchema: z.ZodObject<{
+    keyword: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    location_code: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    language_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    match_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    cpc: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    ad_clicks: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    ad_cost: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    ad_impressions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$loose>;
+export type AdsTrafficItem = z.infer<typeof adsTrafficItemSchema>;
+/** Availability of the Google Ads dataset for a country. */
+export declare const adsStatusItemSchema: z.ZodObject<{
+    country_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type AdsStatusItem = z.infer<typeof adsStatusItemSchema>;
+/** Geo scoping for the Google Ads endpoints. */
+export interface AdsGeoInput {
+    /** DataForSEO location code (e.g. 2840). */
+    locationCode?: number;
+    /**
+     * Canonical DataForSEO location name (e.g. "Pittsburgh,Pennsylvania,United
+     * States"). Google Ads accepts any geotarget, so a name scopes the metrics
+     * to a city or a region instead of a whole country.
+     */
+    locationName?: string;
+    /** DataForSEO language code (e.g. "en"). */
+    languageCode: string;
+}
+export interface AdsSearchVolumeInput extends AdsGeoInput {
+    keywords: string[];
+}
+export interface AdsKeywordsForKeywordsInput extends AdsGeoInput {
+    keywords: string[];
+    /** DataForSEO sort order, e.g. "search_volume". */
+    sortBy?: string;
+    /** Maximum rows to keep (the endpoint returns far more). */
+    limit?: number;
+}
+export interface AdsKeywordsForSiteInput extends AdsGeoInput {
+    /** Domain or URL of the site. */
+    target: string;
+    limit?: number;
+}
+export interface AdsTrafficByKeywordsInput extends AdsGeoInput {
+    keywords: string[];
+    matchType?: string;
+    limit?: number;
+}
+/**
+ * Client for the DataForSEO Google Ads (Keywords Data) endpoints.
+ */
+export declare class DataForSeoGoogleAdsClient {
+    readonly transport: DataForSeoTransport;
+    constructor(options?: DataForSeoGoogleAdsClientOptions);
+    /** Monthly search volume, CPC and competition for a batch of keywords. */
+    searchVolume(input: AdsSearchVolumeInput): Promise<AdsKeywordItem[]>;
+    /** Keyword suggestions derived from a seed keyword. */
+    keywordsForKeywords(input: AdsKeywordsForKeywordsInput): Promise<AdsKeywordItem[]>;
+    /** Keywords a site is bidding on (Google Ads keyword list). */
+    keywordsForSite(input: AdsKeywordsForSiteInput): Promise<AdsKeywordItem[]>;
+    /** Estimated ad traffic (clicks, cost, impressions) for a batch of keywords. */
+    adTrafficByKeywords(input: AdsTrafficByKeywordsInput): Promise<AdsTrafficItem[]>;
+    /** Free availability of the Google Ads dataset, per country. */
+    status(): Promise<AdsStatusItem[]>;
+}
+/** Convenience factory for {@link DataForSeoGoogleAdsClient}. */
+export declare function createDataForSeoGoogleAdsClient(options?: DataForSeoGoogleAdsClientOptions): DataForSeoGoogleAdsClient;