gdelt-ts-client 1.0.0

package/dist/types/query-builder.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Enhanced query builder with TypeScript template literal types and IntelliSense support
+ */
+/**
+ * Fluent query builder for constructing complex GDELT queries with type safety
+ */
+export declare class QueryBuilder {
+    private components;
+    /**
+     * Add a basic search term or phrase
+     */
+    search(term: string): this;
+    /**
+     * Add a phrase search (exact match)
+     */
+    phrase(phrase: string): this;
+    /**
+     * Add multiple terms with OR logic
+     */
+    anyOf(...terms: string[]): this;
+    /**
+     * Add multiple terms with AND logic
+     */
+    allOf(...terms: string[]): this;
+    /**
+     * Exclude a term or phrase
+     */
+    not(term: string): this;
+    /**
+     * Filter by domain
+     */
+    fromDomain(domain: string, exact?: boolean): this;
+    /**
+     * Filter by source country
+     */
+    fromCountry(country: string): this;
+    /**
+     * Filter by source language
+     */
+    inLanguage(language: string): this;
+    /**
+     * Filter by tone (emotional sentiment)
+     */
+    withTone(operator: '>' | '<' | '=', value: number): this;
+    /**
+     * Filter by absolute tone (emotional intensity)
+     */
+    withAbsoluteTone(operator: '>' | '<' | '=', value: number): this;
+    /**
+     * Filter for positive tone articles
+     */
+    withPositiveTone(threshold?: number): this;
+    /**
+     * Filter for negative tone articles
+     */
+    withNegativeTone(threshold?: number): this;
+    /**
+     * Filter for neutral tone articles
+     */
+    withNeutralTone(range?: number): this;
+    /**
+     * Filter for highly emotional articles (regardless of positive/negative)
+     */
+    withHighEmotion(threshold?: number): this;
+    /**
+     * Filter by GDELT theme
+     */
+    withTheme(theme: string): this;
+    /**
+     * Filter for images with specific tags
+     */
+    withImageTag(tag: string): this;
+    /**
+     * Filter for images with web tags
+     */
+    withImageWebTag(tag: string): this;
+    /**
+     * Filter for images with OCR/metadata content
+     */
+    withImageOCR(content: string): this;
+    /**
+     * Filter by image face count
+     */
+    withImageFaceCount(operator: '>' | '<' | '=', count: number): this;
+    /**
+     * Filter by image face tone
+     */
+    withImageFaceTone(operator: '>' | '<' | '=', tone: number): this;
+    /**
+     * Filter by how often image appears on web
+     */
+    withImageWebCount(operator: '>' | '<' | '=', count: number): this;
+    /**
+     * Filter for novel images (rarely seen on web)
+     */
+    withNovelImages(threshold?: number): this;
+    /**
+     * Filter for popular images (frequently seen on web)
+     */
+    withPopularImages(threshold?: number): this;
+    /**
+     * Add proximity constraint (words must appear within distance)
+     */
+    withProximity(distance: number, ...words: string[]): this;
+    /**
+     * Require word to appear minimum number of times
+     */
+    withRepeat(count: number, word: string): this;
+    /**
+     * Add custom query component
+     */
+    custom(query: string): this;
+    /**
+     * Group current components with parentheses
+     */
+    group(): this;
+    /**
+     * Clear all components and start fresh
+     */
+    clear(): this;
+    /**
+     * Build the final query string
+     */
+    build(): string;
+    /**
+     * Get a copy of the current components
+     */
+    getComponents(): string[];
+    /**
+     * Check if the builder has any components
+     */
+    isEmpty(): boolean;
+}
+/**
+ * Query builder specialized for article searches
+ */
+export declare class ArticleQueryBuilder extends QueryBuilder {
+    /**
+     * Search for breaking news articles
+     */
+    breakingNews(): this;
+    /**
+     * Search for opinion articles
+     */
+    opinions(): this;
+    /**
+     * Search for local news
+     */
+    localNews(location?: string): this;
+}
+/**
+ * Query builder specialized for image searches
+ */
+export declare class ImageQueryBuilder extends QueryBuilder {
+    /**
+     * Search for violent content images
+     */
+    violentContent(): this;
+    /**
+     * Search for medical content images
+     */
+    medicalContent(): this;
+    /**
+     * Search for disaster-related images
+     */
+    disasters(): this;
+    /**
+     * Search for political event images
+     */
+    politicalEvents(): this;
+    /**
+     * Search for happy/positive images
+     */
+    positiveImages(): this;
+    /**
+     * Search for sad/negative images
+     */
+    negativeImages(): this;
+}
+/**
+ * Create a new general query builder
+ */
+export declare function createQuery(): QueryBuilder;
+/**
+ * Create a new article-specialized query builder
+ */
+export declare function createArticleQuery(): ArticleQueryBuilder;
+/**
+ * Create a new image-specialized query builder
+ */
+export declare function createImageQuery(): ImageQueryBuilder;
+/**
+ * Create a quick phrase query
+ */
+export declare function phrase(text: string): string;
+/**
+ * Create a quick OR query
+ */
+export declare function anyOf(...terms: string[]): string;
+/**
+ * Create a quick exclusion query
+ */
+export declare function exclude(term: string): string;
+/**
+ * Create a domain filter
+ */
+export declare function fromDomain(domain: string, exact?: boolean): string;
+/**
+ * Create a country filter
+ */
+export declare function fromCountry(country: string): string;
+/**
+ * Create a language filter
+ */
+export declare function inLanguage(language: string): string;
+/**
+ * Create a tone filter
+ */
+export declare function withTone(operator: '>' | '<' | '=', value: number): string;
+/**
+ * Create a theme filter
+ */
+export declare function withTheme(theme: string): string;
+/**
+ * Validate that a query string is well-formed
+ */
+export declare function isValidQuery(query: string): boolean;
+/**
+ * Validate that a query has balanced quotes
+ */
+export declare function hasBalancedQuotes(query: string): boolean;
+/**
+ * Get query complexity score (approximate)
+ */
+export declare function getQueryComplexity(query: string): number;
+export declare const QueryHelpers: {
+    readonly createQuery: typeof createQuery;
+    readonly createArticleQuery: typeof createArticleQuery;
+    readonly createImageQuery: typeof createImageQuery;
+    readonly phrase: typeof phrase;
+    readonly anyOf: typeof anyOf;
+    readonly exclude: typeof exclude;
+    readonly fromDomain: typeof fromDomain;
+    readonly fromCountry: typeof fromCountry;
+    readonly inLanguage: typeof inLanguage;
+    readonly withTone: typeof withTone;
+    readonly withTheme: typeof withTheme;
+    readonly isValidQuery: typeof isValidQuery;
+    readonly hasBalancedQuotes: typeof hasBalancedQuotes;
+    readonly getQueryComplexity: typeof getQueryComplexity;
+};
+//# sourceMappingURL=query-builder.d.ts.map

package/dist/types/query-builder.d.ts.map

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

package/dist/types/query-builder.js

@@ -0,0 +1,458 @@
+"use strict";
+/**
+ * Enhanced query builder with TypeScript template literal types and IntelliSense support
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryHelpers = exports.ImageQueryBuilder = exports.ArticleQueryBuilder = exports.QueryBuilder = void 0;
+exports.createQuery = createQuery;
+exports.createArticleQuery = createArticleQuery;
+exports.createImageQuery = createImageQuery;
+exports.phrase = phrase;
+exports.anyOf = anyOf;
+exports.exclude = exclude;
+exports.fromDomain = fromDomain;
+exports.fromCountry = fromCountry;
+exports.inLanguage = inLanguage;
+exports.withTone = withTone;
+exports.withTheme = withTheme;
+exports.isValidQuery = isValidQuery;
+exports.hasBalancedQuotes = hasBalancedQuotes;
+exports.getQueryComplexity = getQueryComplexity;
+/* eslint-disable @typescript-eslint/explicit-member-accessibility, @typescript-eslint/naming-convention, @typescript-eslint/prefer-nullish-coalescing */
+// Import only what we need to avoid circular dependencies
+// ===== QUERY BUILDER CLASS =====
+/**
+ * Fluent query builder for constructing complex GDELT queries with type safety
+ */
+class QueryBuilder {
+    constructor() {
+        this.components = [];
+    }
+    /**
+     * Add a basic search term or phrase
+     */
+    search(term) {
+        this.components.push(term);
+        return this;
+    }
+    /**
+     * Add a phrase search (exact match)
+     */
+    phrase(phrase) {
+        this.components.push(`"${phrase}"`);
+        return this;
+    }
+    /**
+     * Add multiple terms with OR logic
+     */
+    anyOf(...terms) {
+        if (terms.length > 1) {
+            this.components.push(`(${terms.join(' OR ')})`);
+        }
+        else if (terms.length === 1 && terms[0]) {
+            this.components.push(terms[0]);
+        }
+        return this;
+    }
+    /**
+     * Add multiple terms with AND logic
+     */
+    allOf(...terms) {
+        terms.forEach(term => this.components.push(term));
+        return this;
+    }
+    /**
+     * Exclude a term or phrase
+     */
+    not(term) {
+        this.components.push(`-${term}`);
+        return this;
+    }
+    /**
+     * Filter by domain
+     */
+    fromDomain(domain, exact = false) {
+        const operator = exact ? 'domainis' : 'domain';
+        this.components.push(`${operator}:${domain}`);
+        return this;
+    }
+    /**
+     * Filter by source country
+     */
+    fromCountry(country) {
+        this.components.push(`sourcecountry:${country}`);
+        return this;
+    }
+    /**
+     * Filter by source language
+     */
+    inLanguage(language) {
+        this.components.push(`sourcelang:${language}`);
+        return this;
+    }
+    /**
+     * Filter by tone (emotional sentiment)
+     */
+    withTone(operator, value) {
+        this.components.push(`tone${operator}${value}`);
+        return this;
+    }
+    /**
+     * Filter by absolute tone (emotional intensity)
+     */
+    withAbsoluteTone(operator, value) {
+        this.components.push(`toneabs${operator}${value}`);
+        return this;
+    }
+    /**
+     * Filter for positive tone articles
+     */
+    withPositiveTone(threshold = 2) {
+        return this.withTone('>', threshold);
+    }
+    /**
+     * Filter for negative tone articles
+     */
+    withNegativeTone(threshold = -2) {
+        return this.withTone('<', threshold);
+    }
+    /**
+     * Filter for neutral tone articles
+     */
+    withNeutralTone(range = 1) {
+        this.components.push(`toneabs<${range}`);
+        return this;
+    }
+    /**
+     * Filter for highly emotional articles (regardless of positive/negative)
+     */
+    withHighEmotion(threshold = 5) {
+        return this.withAbsoluteTone('>', threshold);
+    }
+    /**
+     * Filter by GDELT theme
+     */
+    withTheme(theme) {
+        this.components.push(`theme:${theme.toUpperCase()}`);
+        return this;
+    }
+    /**
+     * Filter for images with specific tags
+     */
+    withImageTag(tag) {
+        this.components.push(`imagetag:"${tag}"`);
+        return this;
+    }
+    /**
+     * Filter for images with web tags
+     */
+    withImageWebTag(tag) {
+        this.components.push(`imagewebtag:"${tag}"`);
+        return this;
+    }
+    /**
+     * Filter for images with OCR/metadata content
+     */
+    withImageOCR(content) {
+        this.components.push(`imageocrmeta:"${content}"`);
+        return this;
+    }
+    /**
+     * Filter by image face count
+     */
+    withImageFaceCount(operator, count) {
+        this.components.push(`imagenumfaces${operator}${count}`);
+        return this;
+    }
+    /**
+     * Filter by image face tone
+     */
+    withImageFaceTone(operator, tone) {
+        this.components.push(`imagefacetone${operator}${tone}`);
+        return this;
+    }
+    /**
+     * Filter by how often image appears on web
+     */
+    withImageWebCount(operator, count) {
+        this.components.push(`imagewebcount${operator}${count}`);
+        return this;
+    }
+    /**
+     * Filter for novel images (rarely seen on web)
+     */
+    withNovelImages(threshold = 10) {
+        return this.withImageWebCount('<', threshold);
+    }
+    /**
+     * Filter for popular images (frequently seen on web)
+     */
+    withPopularImages(threshold = 100) {
+        return this.withImageWebCount('>', threshold);
+    }
+    /**
+     * Add proximity constraint (words must appear within distance)
+     */
+    withProximity(distance, ...words) {
+        if (words.length >= 2) {
+            this.components.push(`near${distance}:"${words.join(' ')}"`);
+        }
+        return this;
+    }
+    /**
+     * Require word to appear minimum number of times
+     */
+    withRepeat(count, word) {
+        this.components.push(`repeat${count}:"${word}"`);
+        return this;
+    }
+    /**
+     * Add custom query component
+     */
+    custom(query) {
+        this.components.push(query);
+        return this;
+    }
+    /**
+     * Group current components with parentheses
+     */
+    group() {
+        if (this.components.length > 1) {
+            const grouped = `(${this.components.join(' ')})`;
+            this.components = [grouped];
+        }
+        return this;
+    }
+    /**
+     * Clear all components and start fresh
+     */
+    clear() {
+        this.components = [];
+        return this;
+    }
+    /**
+     * Build the final query string
+     */
+    build() {
+        return this.components.join(' ');
+    }
+    /**
+     * Get a copy of the current components
+     */
+    getComponents() {
+        return [...this.components];
+    }
+    /**
+     * Check if the builder has any components
+     */
+    isEmpty() {
+        return this.components.length === 0;
+    }
+}
+exports.QueryBuilder = QueryBuilder;
+// ===== SPECIALIZED QUERY BUILDERS =====
+/**
+ * Query builder specialized for article searches
+ */
+class ArticleQueryBuilder extends QueryBuilder {
+    /**
+     * Search for breaking news articles
+     */
+    breakingNews() {
+        return this.anyOf('breaking', 'urgent', 'just in', 'developing');
+    }
+    /**
+     * Search for opinion articles
+     */
+    opinions() {
+        return this.anyOf('opinion', 'editorial', 'commentary', 'analysis');
+    }
+    /**
+     * Search for local news
+     */
+    localNews(location) {
+        if (location) {
+            return this.allOf('local', location);
+        }
+        return this.search('local');
+    }
+}
+exports.ArticleQueryBuilder = ArticleQueryBuilder;
+/**
+ * Query builder specialized for image searches
+ */
+class ImageQueryBuilder extends QueryBuilder {
+    /**
+     * Search for violent content images
+     */
+    violentContent() {
+        return this.withImageTag('safesearchviolence');
+    }
+    /**
+     * Search for medical content images
+     */
+    medicalContent() {
+        return this.withImageTag('safesearchmedical');
+    }
+    /**
+     * Search for disaster-related images
+     */
+    disasters() {
+        return this.anyOf('imagetag:"flood"', 'imagetag:"fire"', 'imagetag:"earthquake"', 'imagetag:"rubble"');
+    }
+    /**
+     * Search for political event images
+     */
+    politicalEvents() {
+        return this.anyOf('imagetag:"crowd"', 'imagetag:"protest"', 'imagetag:"rally"', 'imagetag:"podium"');
+    }
+    /**
+     * Search for happy/positive images
+     */
+    positiveImages() {
+        return this.withImageFaceTone('>', 1);
+    }
+    /**
+     * Search for sad/negative images
+     */
+    negativeImages() {
+        return this.withImageFaceTone('<', -1);
+    }
+}
+exports.ImageQueryBuilder = ImageQueryBuilder;
+// ===== QUERY HELPER FUNCTIONS =====
+/**
+ * Create a new general query builder
+ */
+function createQuery() {
+    return new QueryBuilder();
+}
+/**
+ * Create a new article-specialized query builder
+ */
+function createArticleQuery() {
+    return new ArticleQueryBuilder();
+}
+/**
+ * Create a new image-specialized query builder
+ */
+function createImageQuery() {
+    return new ImageQueryBuilder();
+}
+/**
+ * Create a quick phrase query
+ */
+function phrase(text) {
+    return `"${text}"`;
+}
+/**
+ * Create a quick OR query
+ */
+function anyOf(...terms) {
+    if (terms.length === 0)
+        return '';
+    if (terms.length === 1)
+        return terms[0] || '';
+    return `(${terms.join(' OR ')})`;
+}
+/**
+ * Create a quick exclusion query
+ */
+function exclude(term) {
+    return `-${term}`;
+}
+/**
+ * Create a domain filter
+ */
+function fromDomain(domain, exact = false) {
+    const operator = exact ? 'domainis' : 'domain';
+    return `${operator}:${domain}`;
+}
+/**
+ * Create a country filter
+ */
+function fromCountry(country) {
+    return `sourcecountry:${country}`;
+}
+/**
+ * Create a language filter
+ */
+function inLanguage(language) {
+    return `sourcelang:${language}`;
+}
+/**
+ * Create a tone filter
+ */
+function withTone(operator, value) {
+    return `tone${operator}${value}`;
+}
+/**
+ * Create a theme filter
+ */
+function withTheme(theme) {
+    return `theme:${theme.toUpperCase()}`;
+}
+// ===== QUERY VALIDATION HELPERS =====
+/**
+ * Validate that a query string is well-formed
+ */
+function isValidQuery(query) {
+    if (!query || query.trim().length === 0) {
+        return false;
+    }
+    // Check for balanced parentheses
+    let parenCount = 0;
+    for (const char of query) {
+        if (char === '(')
+            parenCount++;
+        if (char === ')')
+            parenCount--;
+        if (parenCount < 0)
+            return false;
+    }
+    return parenCount === 0;
+}
+/**
+ * Validate that a query has balanced quotes
+ */
+function hasBalancedQuotes(query) {
+    const quotes = query.match(/"/g);
+    return !quotes || quotes.length % 2 === 0;
+}
+/**
+ * Get query complexity score (approximate)
+ */
+function getQueryComplexity(query) {
+    let complexity = 0;
+    // Base complexity
+    complexity += query.split(' ').length;
+    // Operators add complexity
+    complexity += (query.match(/\bOR\b/g) || []).length * 2;
+    complexity += (query.match(/\bAND\b/g) || []).length * 1;
+    complexity += (query.match(/\bNOT\b/g) || []).length * 1;
+    // Special operators add complexity
+    const operatorPattern = /\b(?:domain|domainis|sourcecountry|sourcelang|theme|tone|toneabs|imagetag|imagewebtag|imageocrmeta|imagenumfaces|imagefacetone|imagewebcount):/g;
+    complexity += (query.match(operatorPattern) || []).length * 3;
+    // Proximity and repeat operators
+    complexity += (query.match(/\bnear\d+:/g) || []).length * 4;
+    complexity += (query.match(/\brepeat\d+:/g) || []).length * 2;
+    return complexity;
+}
+// ===== EXPORT EVERYTHING =====
+exports.QueryHelpers = {
+    createQuery,
+    createArticleQuery,
+    createImageQuery,
+    phrase,
+    anyOf,
+    exclude,
+    fromDomain,
+    fromCountry,
+    inLanguage,
+    withTone,
+    withTheme,
+    isValidQuery,
+    hasBalancedQuotes,
+    getQueryComplexity
+};
+//# sourceMappingURL=query-builder.js.map