@graphext/cuery 0.2.0

package/esm/src/tools/keywords.d.ts

@@ -0,0 +1,21 @@
+import type { KeywordsOptions } from '../schemas/keyword.schema.js';
+import { type KeywordsResponse } from '../schemas/keyword.schema.js';
+import { type KeywordRecord } from '../apis/googleAds/keywordPlanner.js';
+export interface ExpandKeywordsParams {
+    seedKeywords: Array<string | Array<string>>;
+    url?: string;
+    urlAsExpandRelevanceContext?: string;
+    language?: string;
+    countryISOCode?: string | null;
+    generateIdeasFromSeeds?: boolean;
+    /** When true, adds deduplicatedKeywords column with all keywords sharing the same metrics */
+    includeDeduplicatedKeywords?: boolean;
+    /** When true, includes seedKeywords column in output records. Defaults to false. */
+    includeSeedKeywords?: boolean;
+    /** When true, generates a separate dataset with all keywords (dedup by keyword only). Defaults to false. */
+    includeAllKeywordsDataset?: boolean;
+}
+export declare function expandKeywords({ seedKeywords, url, urlAsExpandRelevanceContext, language, countryISOCode, generateIdeasFromSeeds, includeSeedKeywords }: ExpandKeywordsParams): Promise<Array<Array<KeywordRecord>>>;
+export declare function generateKeywords({ sector, market, brand, brandDomain, language, userLanguage, model, briefing, instructions, keywords, brands, personas, funnel }: KeywordsOptions): Promise<KeywordsResponse>;
+export * from '../schemas/keyword.schema.js';
+//# sourceMappingURL=keywords.d.ts.map

package/esm/src/tools/keywords.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keywords.d.ts","sourceRoot":"","sources":["../../../src/src/tools/keywords.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAE7F,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAE3G,MAAM,WAAW,oBAAoB;IACpC,YAAY,EAAE,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,6FAA6F;IAC7F,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,oFAAoF;IACpF,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,4GAA4G;IAC5G,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAsB,cAAc,CAAC,EACpC,YAAY,EACZ,GAAG,EACH,2BAA2B,EAC3B,QAAe,EACf,cAAc,EACd,sBAA8B,EAC9B,mBAA2B,EAC3B,EAAE,oBAAoB,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAsC7D;AAiGD,wBAAsB,gBAAgB,CAAC,EACtC,MAAM,EACN,MAAM,EACN,KAAK,EACL,WAAW,EACX,QAAoB,EACpB,YAAmB,EACnB,KAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,QAAe,EACf,MAAa,EACb,QAAe,EACf,MAAa,EACb,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA8D7C;AAED,cAAc,8BAA8B,CAAC"}

package/esm/src/tools/keywords.js

@@ -0,0 +1,172 @@
+import { mapParallel } from '../async.js';
+import { askOpenAISafe } from '../openai.js';
+import { buildBrandContext } from './brands.js';
+import { KeywordsResponseSchema } from '../schemas/keyword.schema.js';
+import { dedent } from '../utils.js';
+import { keywords as getGoogleAdsKeywords } from '../apis/googleAds/keywordPlanner.js';
+export async function expandKeywords({ seedKeywords, url, urlAsExpandRelevanceContext, language = 'EN', countryISOCode, generateIdeasFromSeeds = false, includeSeedKeywords = false }) {
+    url = url?.trim();
+    language = language?.trim();
+    countryISOCode = countryISOCode?.trim();
+    const expandedKeywords = [];
+    const keywordIdeasPromise = mapParallel(seedKeywords, 2, async (keyword) => {
+        const keywordData = await getGoogleAdsKeywords({
+            keywords: Array.isArray(keyword) ? keyword : [keyword],
+            ideas: generateIdeasFromSeeds, // Configurable: get data for seed keywords OR generate ideas
+            language,
+            countryISOCode,
+            url: generateIdeasFromSeeds != null ? urlAsExpandRelevanceContext : undefined,
+            includeSeedKeywords
+        });
+        expandedKeywords.push(keywordData);
+    });
+    const urlIdeasPromise = url
+        ? getGoogleAdsKeywords({
+            url,
+            wholeSite: true,
+            ideas: true, // Generate keyword ideas from URL
+            maxIdeas: 10000,
+            language,
+            countryISOCode,
+            includeSeedKeywords
+        }).then(ideas => expandedKeywords.push(ideas))
+        : Promise.resolve([]);
+    await Promise.all([keywordIdeasPromise, urlIdeasPromise]);
+    return expandedKeywords;
+}
+const GENERATE_KEYWORDS_PROMPT = dedent(`
+You're a keyword research expert helping a brand in the {sector} sector targeting the {market} market.
+
+For context, the brand being analyzed is{brand_context}. Use this brand as context to better understand
+the specific niche, positioning, and target audience within the {sector} sector.
+
+{brandsInfo}
+
+{personasInfo}
+
+{funnelInfo}
+
+# Your Task
+
+You must follow the user's instructions below. The instructions will tell you EXACTLY what to do with keywords.
+
+**CRITICAL**: Only generate new keywords if the instructions EXPLICITLY ask you to generate, add, create,
+or suggest keywords. If the instructions ask for something else (like analysis, filtering, removing, or
+any other operation), do NOT generate new keywords - instead, perform only what is requested.
+
+If you are asked to generate keywords, they should be:
+- Broad enough (1-3 words typically) for Google Keyword Planner seed expansion
+- Natural search queries that real users would type
+- Mix of informational and transactional intent
+- Focused on the sector and market context
+- Consider the customer personas and their search behaviors if provided
+- Cover different funnel stages if funnel information is provided
+- Do NOT include brand names{brand_exclusion}
+
+IMPORTANT: Any "keywordSeeds" fields you see in the brands, personas, or funnel data above are for REFERENCE ONLY
+to help you understand the context - they are managed separately and you should NOT include them in your output.
+
+Return keywords as a list of strings in language {language}.
+
+Make sure your answer is in the language "{userLanguage}" except the keywords themselves, which should
+maintain the original language {language}.
+
+Also provide an "explanation" field with a brief summary (2-3 sentences) explaining what you did
+based on the instructions.
+
+# User Instructions
+
+{instructions}
+
+{currentKeywordsInfo}
+`);
+const CURRENT_KEYWORDS_CLAUSE = dedent(`
+# Current Custom Keywords
+
+The following is the current list of custom keywords the user has.
+
+{currentData}
+
+**CRITICAL**: Unless the instructions EXPLICITLY ask you to generate, add, create, or suggest NEW keywords,
+you MUST return EXACTLY the same keywords that are in the current data (possibly modified per instructions
+like filtering or removing). Do NOT automatically generate new keywords - only do so if explicitly requested.
+`);
+const BRANDS_CLAUSE = dedent(`
+# Brands Information (Reference Only)
+
+The following brands (including competitors) are relevant to this analysis:
+
+{brandsData}
+
+Use this information to understand the competitive landscape and generate custom keywords that could help
+the brand compete effectively. Consider the products, services, and market positions of these brands.
+NOTE: Any "keywordSeeds" in the portfolio items are for reference only - do not include them directly in your output.
+`);
+const PERSONAS_CLAUSE = dedent(`
+# Customer Personas (Reference Only)
+
+The following customer personas represent the target audience:
+
+{personasData}
+
+Generate custom keywords that these personas would naturally search for based on their characteristics,
+needs, and behaviors. Consider their language, expertise level, and search intent.
+NOTE: Any "keywordSeeds" in the personas are for reference only - do not include them directly in your output.
+`);
+const FUNNEL_CLAUSE = dedent(`
+# Marketing Funnel (Reference Only)
+
+The following marketing funnel defines the customer journey stages:
+
+{funnelData}
+
+Generate custom keywords that cover different stages of this funnel, from awareness to conversion.
+Consider the goals and categories at each stage to ensure comprehensive keyword coverage.
+NOTE: Any "keywordSeeds" in the funnel categories are for reference only - do not include them directly in your output.
+`);
+export async function generateKeywords({ sector, market, brand, brandDomain, language = 'english', userLanguage = null, model = 'gpt-4.1', briefing, instructions, keywords = null, brands = null, personas = null, funnel = null }) {
+    if (!brand && !brandDomain) {
+        throw new Error('Either brand or brandDomain must be provided');
+    }
+    const brandContext = buildBrandContext({
+        brand,
+        brandDomain,
+        sector,
+        market,
+        briefing
+    });
+    let brandExclusion;
+    if (brandDomain) {
+        if (brand) {
+            brandExclusion = ` "${brand}" or the domain`;
+        }
+        else {
+            brandExclusion = ' or domain';
+        }
+    }
+    else {
+        brandExclusion = ` "${brand}"`;
+    }
+    const currentData = keywords && keywords.length > 0 ? CURRENT_KEYWORDS_CLAUSE.replace('{currentData}', JSON.stringify({ keywords }, null, 2)) : null;
+    const brandsInfo = brands && brands.length > 0 ? BRANDS_CLAUSE.replace('{brandsData}', JSON.stringify(brands, null, 2)) : null;
+    const personasInfo = personas && personas.length > 0 ? PERSONAS_CLAUSE.replace('{personasData}', JSON.stringify(personas, null, 2)) : null;
+    const funnelInfo = funnel != null ? FUNNEL_CLAUSE.replace('{funnelData}', JSON.stringify(funnel, null, 2)) : null;
+    const content = GENERATE_KEYWORDS_PROMPT
+        .replaceAll('{sector}', sector)
+        .replaceAll('{market}', market)
+        .replaceAll('{brand_context}', brandContext)
+        .replaceAll('{brand_exclusion}', brandExclusion)
+        .replaceAll('{language}', language)
+        .replaceAll('{userLanguage}', userLanguage ?? language)
+        .replaceAll('{instructions}', instructions || '')
+        .replaceAll('{currentKeywordsInfo}', currentData || '')
+        .replaceAll('{brandsInfo}', brandsInfo || '')
+        .replaceAll('{personasInfo}', personasInfo || '')
+        .replaceAll('{funnelInfo}', funnelInfo || '');
+    const { parsed } = await askOpenAISafe(content, model, KeywordsResponseSchema);
+    if (!parsed) {
+        throw new Error('Failed to parse response from OpenAI');
+    }
+    return parsed;
+}
+export * from '../schemas/keyword.schema.js';

package/esm/src/tools/personas.d.ts

@@ -0,0 +1,3 @@
+import type { PersonasOptions, PersonasResponse } from '../schemas/persona.schema.js';
+export declare function generatePersonas({ sector, market, brand, brandDomain, language, userLanguage, count, model, briefing, instructions, personas }: PersonasOptions): Promise<PersonasResponse>;
+//# sourceMappingURL=personas.d.ts.map

package/esm/src/tools/personas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"personas.d.ts","sourceRoot":"","sources":["../../../src/src/tools/personas.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAkDtF,wBAAsB,gBAAgB,CAAC,EACtC,MAAM,EACN,MAAM,EACN,KAAK,EACL,WAAW,EACX,QAAoB,EACpB,YAAmB,EACnB,KAAS,EACT,KAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,QAAe,EACf,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA4C7C"}

package/esm/src/tools/personas.js

@@ -0,0 +1,88 @@
+import { askOpenAISafe } from '../openai.js';
+import { buildBrandContext } from './brands.js';
+import { PersonasResponseSchema } from '../schemas/persona.schema.js';
+import { dedent } from '../utils.js';
+const PROMPT = dedent(`
+You're a marketing expert identifying typical profiles/personas of people searching
+for brands, products or services. Generate {count} detailed customer personas for a brand
+in the {sector} sector targeting the {market} market.
+
+For context, the brand being analyzed is{brand_context}. Use this brand as context to better understand
+the specific niche, positioning, and target audience within the {sector} sector. However, you MUST NOT
+mention the brand name{brand_exclusion} anywhere in the persona names or descriptions. The personas should be
+generic profiles that could apply to similar brands in the same space.
+
+Each persona should include:
+- name: A short and catchy name, such as "Tech-Savvy Creative Director", "Gaming Industry Veteran",
+  "Eco-Conscious Millennial", "Budget-Conscious Family Planner", or "Luxury Lifestyle Enthusiast".
+- description: A brief description of the persona's characteristics, needs, and behaviors.
+- keywordSeeds: A list of 5-10 keyword seed phrases in language {language} that this persona would typically search for
+  when looking for products/services in this space. These should be realistic search queries that
+  reflect the persona's language ({language}), intent, and level of expertise. Include a mix of informational
+  and transactional queries. Keywords should be broad (1-3 words) suitable for Google Keyword Planner
+  seed expansion. Do NOT include the brand name {brand_exclusion} in these keywords.
+
+Make sure you're answer is in the language "{userLanguage} except keywordSeeds, that should maintain the original language {language}".
+
+Return the personas as a list of JSON objects.
+
+Also provide an "explanation" field with a brief summary (2-3 sentences) explaining the reasoning behind
+the personas you generated: why these profiles are relevant for this sector and market, and what key
+customer segments they represent.
+
+{instructions}
+
+{currentPersonasInfo}
+`);
+const CURRENT_DATA_CLAUSE = dedent(`
+# Current Personas Information
+
+The following is the current information the user has about personas for the brand(s).
+
+{currentData}
+
+IMPORTANT: Unless the instructions explicitly specify to modify, replace, add, or remove competitors
+from this list, you MUST return at least all the same competitors that are already present in the
+current data. If no modification instructions are provided, maintain the existing list and only add
+new competitors if they are relevant.
+`);
+export async function generatePersonas({ sector, market, brand, brandDomain, language = 'english', userLanguage = null, count = 5, model = 'gpt-4.1', briefing, instructions, personas = null }) {
+    if (!brand && !brandDomain) {
+        throw new Error('Either brand or brandDomain must be provided');
+    }
+    const brandContext = buildBrandContext({
+        brand,
+        brandDomain,
+        sector,
+        market,
+        briefing
+    });
+    let brandExclusion;
+    if (brandDomain) {
+        if (brand) {
+            brandExclusion = ` "${brand}" or the domain`;
+        }
+        else {
+            brandExclusion = ' or domain';
+        }
+    }
+    else {
+        brandExclusion = ` "${brand}"`;
+    }
+    const currentData = personas && personas.length > 0 ? CURRENT_DATA_CLAUSE.replace('{currentData}', JSON.stringify({ personas }, null, 2)) : null;
+    const content = PROMPT
+        .replace('{count}', count.toString())
+        .replaceAll('{sector}', sector)
+        .replaceAll('{market}', market)
+        .replaceAll('{brand_context}', brandContext)
+        .replaceAll('{brand_exclusion}', brandExclusion)
+        .replaceAll('{language}', language)
+        .replaceAll('{userLanguage}', userLanguage ?? language)
+        .replaceAll('{instructions}', instructions || '')
+        .replaceAll('{currentPersonasInfo}', currentData || '');
+    const { parsed } = await askOpenAISafe(content, model, PersonasResponseSchema);
+    if (!parsed) {
+        throw new Error('Failed to parse response from OpenAI');
+    }
+    return parsed;
+}

package/esm/src/tools/scorer.d.ts

@@ -0,0 +1,14 @@
+import { z } from '../../deps/jsr.io/@zod/zod/4.1.12/src/index.js';
+export type ScoreSchema = z.ZodObject<{
+    value: z.ZodNumber;
+}>;
+/**
+ * Dynamically create a Zod schema for a score based on provided parameters.
+ */
+export declare function makeScoreSchema(type: 'integer' | 'number', min: number, max: number, description: string): ScoreSchema;
+/**
+ * Assumes only remaining placeholder in prompt is {record}
+ */
+export declare function score(record: Record<string, unknown>, prompt: string, schema: ScoreSchema, model?: string): Promise<number>;
+export declare function scoreBatch(records: Array<Record<string, unknown>>, name: string, description: string, type: 'integer' | 'number', min: number, max: number, model?: string, maxConcurrency?: number): Promise<Array<number>>;
+//# sourceMappingURL=scorer.d.ts.map

package/esm/src/tools/scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorer.d.ts","sourceRoot":"","sources":["../../../src/src/tools/scorer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,gDAAgD,CAAC;AAqBnE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,SAAS,CAAC;IAAE,KAAK,EAAE,CAAC,CAAC,SAAS,CAAA;CAAE,CAAC,CAAC;AAE9D;;GAEG;AACH,wBAAgB,eAAe,CAC9B,IAAI,EAAE,SAAS,GAAG,QAAQ,EAC1B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,GACjB,WAAW,CAWb;AAED;;GAEG;AACH,wBAAsB,KAAK,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,EACnB,KAAK,GAAE,MAAuB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAajB;AAED,wBAAsB,UAAU,CAC/B,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,SAAS,GAAG,QAAQ,EAC1B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,MAAuB,EAC9B,cAAc,GAAE,MAAY,GAC1B,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAcxB"}

package/esm/src/tools/scorer.js

@@ -0,0 +1,54 @@
+import { z } from '../../deps/jsr.io/@zod/zod/4.1.12/src/index.js';
+import { mapParallel } from '../async.js';
+import { askOpenAISafe } from '../openai.js';
+import { dedent } from '../utils.js';
+const PROMPT = dedent(`
+# Instructions
+
+Assign a {name} ({type} score between {min} and {max}) to the data record below.
+
+Score description: {description}
+
+Make sure to consider all the attributes of the data record, and assign the score
+based on the content of the attributes.
+
+# Data Record
+
+{record}
+`);
+/**
+ * Dynamically create a Zod schema for a score based on provided parameters.
+ */
+export function makeScoreSchema(type, min, max, description) {
+    let schema;
+    if (type === 'integer') {
+        schema = z.number().int().min(min).max(max).describe(description);
+    }
+    else {
+        schema = z.number().min(min).max(max).describe(description);
+    }
+    return z.object({
+        value: schema
+    });
+}
+/**
+ * Assumes only remaining placeholder in prompt is {record}
+ */
+export async function score(record, prompt, schema, model = 'gpt-4.1-mini') {
+    const renderedPrompt = prompt.replace('record', JSON.stringify(record, null, 2));
+    const response = await askOpenAISafe(renderedPrompt, model, schema);
+    if (response.parsed == null) {
+        throw new Error('Failed to parse score from OpenAI response');
+    }
+    return response.parsed.value;
+}
+export async function scoreBatch(records, name, description, type, min, max, model = 'gpt-4.1-mini', maxConcurrency = 100) {
+    const schema = makeScoreSchema(type, min, max, description);
+    const prompt = PROMPT
+        .replace('{name}', name)
+        .replace('{type}', type)
+        .replace('{min}', min.toString())
+        .replace('{max}', max.toString())
+        .replace('{description}', description);
+    return mapParallel(records, maxConcurrency, (record) => score(record, prompt, schema, model));
+}

package/esm/src/tools/search.d.ts

@@ -0,0 +1,24 @@
+import type { BatchSearchOptions, FormattedSearchOptions, SearchOptions, SearchResult } from '../schemas/search.schema.js';
+export type { SearchResult } from '../schemas/search.schema.js';
+/**
+ * Call OpenAI Responses API with Web Search enabled (async).
+ *
+ * API Docs:
+ * - https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses
+ */
+export declare function searchOpenAI({ prompt, model, useSearch, countryISOCode, contextSize, reasoningEffort, searchTool }: SearchOptions): Promise<SearchResult>;
+/**
+ * Perform a web search using searchOpenAI and return structured response.
+ * The OpenAI API doesn't currently allow both web search tool and response format in the same call.
+ *
+ * This function:
+ * 1. Performs a web search using searchOpenAI
+ * 2. Formats the search results using a template
+ * 3. Sends the formatted results to OpenAI with a Zod schema to extract structured information
+ */
+export declare function searchWithFormat<T>({ prompt, model, responseSchema, useSearch, countryISOCode, contextSize, reasoningEffort }: FormattedSearchOptions<T>): Promise<T>;
+/**
+ * Performs web search for multiple prompts concurrently while preserving order.
+ */
+export declare function searchBatch({ prompts, model, useSearch, countryISOCode, contextSize, reasoningEffort, maxConcurrency }: BatchSearchOptions): Promise<Array<SearchResult>>;
+//# sourceMappingURL=search.d.ts.map

package/esm/src/tools/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/src/tools/search.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAK3H,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,EAClC,MAAM,EACN,KAAsB,EACtB,SAAgB,EAChB,cAAqB,EACrB,WAAmB,EACnB,eAAuB,EACvB,UAAyB,EACzB,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAqBvC;AAqED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,EACzC,MAAM,EACN,KAAK,EACL,cAAc,EACd,SAAgB,EAChB,cAAqB,EACrB,WAAsB,EACtB,eAAuB,EACvB,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA0BxC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAC3B,OAAO,EACP,KAAsB,EACtB,SAAgB,EAChB,cAAqB,EACrB,WAAsB,EACtB,eAAuB,EACvB,cAAoB,EACpB,EAAE,kBAAkB,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAanD"}

package/esm/src/tools/search.js

@@ -0,0 +1,130 @@
+import { mapParallel } from '../async.js';
+import { askOpenAISafe } from '../openai.js';
+import { extractDomain } from '../urls.js';
+import { dedent } from '../utils.js';
+/**
+ * Call OpenAI Responses API with Web Search enabled (async).
+ *
+ * API Docs:
+ * - https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses
+ */
+export async function searchOpenAI({ prompt, model = 'gpt-4.1-mini', useSearch = true, countryISOCode = null, contextSize = 'low', reasoningEffort = 'low', searchTool = 'web_search' }) {
+    const params = {};
+    if (model.includes('-5')) {
+        params.reasoning = { effort: reasoningEffort };
+    }
+    if (useSearch) {
+        params.tools = [{
+                type: searchTool,
+                search_context_size: contextSize,
+                ...(countryISOCode ? { user_location: { type: 'approximate', country: countryISOCode } } : {})
+            }];
+        params.tool_choice = 'required';
+    }
+    const { output } = await askOpenAISafe(prompt, model, undefined, params);
+    if (!output) {
+        throw new Error('No output from OpenAI');
+    }
+    return validateOpenAI(output);
+}
+/**
+ * Convert a raw web search response into a SearchResult instance.
+ */
+function validateOpenAI(response) {
+    let answer = '';
+    let sources = [];
+    // Filter out reasoning elements and find relevant elements
+    const relevantElements = response.filter(item => item.type !== 'reasoning');
+    const messageElement = relevantElements.find(item => item.type === 'message');
+    const hasWebSearch = relevantElements.some(item => item.type === 'web_search_call');
+    if (!messageElement) {
+        throw new Error('No message element found in response');
+    }
+    if (messageElement.type !== 'message') {
+        throw new Error('Message element must be of type "message"');
+    }
+    const content = messageElement.content?.[0];
+    if (!content) {
+        throw new Error('Message element has no content');
+    }
+    if (content.type !== 'output_text') {
+        throw new Error(`Content must be of type "output_text", got "${content.type}"`);
+    }
+    answer = content.text;
+    // Extract sources from annotations if web search was used
+    if (hasWebSearch && content.annotations) {
+        sources = content.annotations
+            .filter(ann => ann.type === 'url_citation')
+            .map(ann => ({
+            title: ann.title,
+            url: ann.url,
+            domain: extractDomain(ann.url)
+        }));
+    }
+    return {
+        answer,
+        sources
+    };
+}
+const FORMATTED_SEARCH_PROMPT = dedent(`
+Based on the following search results, please format the information according
+to the requested structure:
+
+# Search Query
+
+{prompt}
+
+# Search Results
+
+{answer}
+
+# Sources
+
+{sources}
+
+Please extract and format the relevant information from these search results as a JSON object.
+`);
+/**
+ * Perform a web search using searchOpenAI and return structured response.
+ * The OpenAI API doesn't currently allow both web search tool and response format in the same call.
+ *
+ * This function:
+ * 1. Performs a web search using searchOpenAI
+ * 2. Formats the search results using a template
+ * 3. Sends the formatted results to OpenAI with a Zod schema to extract structured information
+ */
+export async function searchWithFormat({ prompt, model, responseSchema, useSearch = true, countryISOCode = null, contextSize = 'medium', reasoningEffort = 'low' }) {
+    const searchResult = await searchOpenAI({
+        prompt,
+        model,
+        useSearch,
+        countryISOCode,
+        contextSize,
+        reasoningEffort
+    });
+    const sources = searchResult.sources
+        .map((source) => `- ${source.title}: ${source.url}`)
+        .join('\n');
+    const formattedPrompt = FORMATTED_SEARCH_PROMPT
+        .replace('{prompt}', prompt)
+        .replace('{answer}', searchResult.answer)
+        .replace('{sources}', sources);
+    const { parsed } = await askOpenAISafe(formattedPrompt, 'gpt-4.1-mini', responseSchema);
+    if (!parsed) {
+        throw new Error('Failed to parse structured response from OpenAI');
+    }
+    return parsed;
+}
+/**
+ * Performs web search for multiple prompts concurrently while preserving order.
+ */
+export function searchBatch({ prompts, model = 'gpt-4.1-mini', useSearch = true, countryISOCode = null, contextSize = 'medium', reasoningEffort = 'low', maxConcurrency = 100 }) {
+    return mapParallel(prompts, maxConcurrency, prompt => searchOpenAI({
+        prompt,
+        model,
+        useSearch,
+        countryISOCode: countryISOCode,
+        contextSize: contextSize,
+        reasoningEffort: reasoningEffort
+    }));
+}

package/esm/src/tools/seedKeywords.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Seed Keyword Functions
+ *
+ * Pure functions for collecting and grouping seed keywords.
+ * No external dependencies - safe to import in both frontend and backend.
+ */
+export type { SeedKeyword, SeedKeywordSource } from '../schemas/seedKeyword.schema.js';
+import type { SeedKeyword } from '../schemas/seedKeyword.schema.js';
+interface PortfolioItemLike {
+    name: string;
+    keywordSeeds?: Array<string>;
+}
+interface PersonaLike {
+    name: string;
+    keywordSeeds?: Array<string>;
+}
+interface FunnelCategoryLike {
+    name: string;
+    keywordSeeds?: Array<string>;
+}
+interface FunnelStageLike {
+    stage: string;
+    categories?: Array<FunnelCategoryLike>;
+}
+interface CompetitorLike {
+    name: string;
+    portfolio?: Array<PortfolioItemLike>;
+}
+export interface CollectSeedKeywordsParams {
+    brandPortfolio?: Array<PortfolioItemLike>;
+    personas?: Array<PersonaLike>;
+    funnelStages?: Array<FunnelStageLike>;
+    competitors?: Array<CompetitorLike>;
+    customKeywords?: Array<string>;
+}
+/**
+ * Collects seed keywords from all sources and creates SeedKeyword objects
+ * with proper metadata (id, source, sourceId, sourceName).
+ */
+export declare function collectSeedKeywords({ brandPortfolio, personas, funnelStages, competitors, customKeywords }: CollectSeedKeywordsParams): Array<SeedKeyword>;
+/**
+ * Groups seed keywords by their source, maintaining order within each source.
+ * Keywords from the same portfolio item, competitor product, or funnel category
+ * are grouped together.
+ *
+ * @param seedKeywords - Flat array of seed keywords
+ * @param generateIdeasFromSeeds - When true, returns grouped keywords for idea generation.
+ *                                  When false, returns all keywords flattened into a single group.
+ * @returns Array of grouped keywords (arrays for same-source groups, single items for personas/custom)
+ */
+export declare function groupSeedKeywords(seedKeywords: Array<SeedKeyword>, generateIdeasFromSeeds?: boolean): Array<Array<SeedKeyword> | SeedKeyword>;
+/**
+ * Groups seed keywords and extracts just the keyword strings.
+ * Convenience wrapper around groupSeedKeywords for cases where
+ * only the keyword text is needed (not the full metadata).
+ */
+export declare function groupKeywordStrings(seedKeywords: Array<SeedKeyword>, generateIdeasFromSeeds?: boolean): Array<Array<string> | string>;
+/**
+ * Collects and groups seed keywords in one step, returning only keyword strings.
+ * This is a convenience function for pipelines that need grouped keyword strings
+ * without the full SeedKeyword metadata.
+ *
+ * @param params - Same parameters as collectSeedKeywords
+ * @param generateIdeasFromSeeds - When true, returns grouped keywords. When false, returns flat.
+ * @returns Grouped keyword strings (arrays for same-source groups, single strings otherwise)
+ */
+export declare function collectAndGroupKeywordStrings(params: CollectSeedKeywordsParams, generateIdeasFromSeeds?: boolean): Array<Array<string> | string>;
+//# sourceMappingURL=seedKeywords.d.ts.map

package/esm/src/tools/seedKeywords.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seedKeywords.d.ts","sourceRoot":"","sources":["../../../src/src/tools/seedKeywords.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAGvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAOpE,UAAU,iBAAiB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED,UAAU,WAAW;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED,UAAU,kBAAkB;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED,UAAU,eAAe;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAC;CACvC;AAED,UAAU,cAAc;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC;CACrC;AAMD,MAAM,WAAW,yBAAyB;IACzC,cAAc,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC9B,YAAY,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IACpC,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EACnC,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,cAAc,EACd,EAAE,yBAAyB,GAAG,KAAK,CAAC,WAAW,CAAC,CA+EhD;AAcD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAChC,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,EAChC,sBAAsB,GAAE,OAAc,GACpC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC,CA8FzC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,EAChC,sBAAsB,GAAE,OAAc,GACpC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAS/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC5C,MAAM,EAAE,yBAAyB,EACjC,sBAAsB,GAAE,OAAc,GACpC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAG/B"}