@graphext/cuery 0.2.0

package/script/src/tools/funnel.js

@@ -0,0 +1,381 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FunnelWithExplanationSchema = void 0;
+exports.iterateFunnelCategories = iterateFunnelCategories;
+exports.funnelToTopics = funnelToTopics;
+exports.customizeFunnel = customizeFunnel;
+exports.generateSeedKeywords = generateSeedKeywords;
+exports.reseedFunnel = reseedFunnel;
+exports.generateFunnel = generateFunnel;
+const async_js_1 = require("../async.js");
+const openai_js_1 = require("../openai.js");
+const funnel_schema_js_1 = require("../schemas/funnel.schema.js");
+Object.defineProperty(exports, "FunnelWithExplanationSchema", { enumerable: true, get: function () { return funnel_schema_js_1.FunnelWithExplanationSchema; } });
+const utils_js_1 = require("../utils.js");
+/**
+ * Iterates over all categories in a funnel, yielding references to stage info and category objects.
+ * This allows in-place modifications of categories within the funnel structure.
+ *
+ * @param funnel - The funnel to iterate over (can be a Funnel object or array of stages)
+ * @yields A tuple of [stageName, stageGoal, categoryObject] where categoryObject can be modified in-place
+ */
+function* iterateFunnelCategories(funnel) {
+    const stages = Array.isArray(funnel) ? funnel : funnel.stages;
+    for (const stageData of stages) {
+        for (const category of stageData.categories) {
+            yield [stageData.stage, stageData.goal, category];
+        }
+    }
+}
+/**
+ * Converts a Funnel into a topic taxonomy structure where stages are top-level topics
+ * and categories are subtopics.
+ *
+ * @param funnel - The funnel to convert (can be a Funnel object or array of stages)
+ * @returns An array of topic objects with stage names as topics and category names as subtopics
+ */
+function funnelToTopics(funnel) {
+    const stages = Array.isArray(funnel) ? funnel : funnel.stages;
+    return stages.map(stage => ({
+        topic: stage.stage,
+        subtopics: stage.categories.map(category => category.name)
+    }));
+}
+const GENERIC_FUNNEL = [
+    {
+        'stage': 'Awareness / Discovery',
+        'goal': 'Problem recognition, education.',
+        'categories': [
+            {
+                'name': 'Problem Identification',
+                'description': 'User searches to understand or define their problem or need.',
+                'keywordPatterns': ['questions', 'how-to', 'why', 'tips', 'guides'],
+                'keywordSeeds': [
+                    'why does my back hurt when running',
+                    'how to organize customer data'
+                ],
+                'intent': 'Informational'
+            },
+            {
+                'name': 'Category Education',
+                'description': 'Exploring broad product/service categories without specific brands.',
+                'keywordPatterns': ['types of', 'what is', 'overview', 'guide to'],
+                'keywordSeeds': ['types of running shoes', 'what is CRM software'],
+                'intent': 'Informational'
+            },
+            {
+                'name': 'Trends & Inspiration',
+                'description': 'Looking for ideas, new trends, or general inspiration.',
+                'keywordPatterns': [
+                    'trends',
+                    'ideas',
+                    'inspiration',
+                    'popular',
+                    'latest'
+                ],
+                'keywordSeeds': [
+                    'latest running shoe trends 2025',
+                    'popular small business tools'
+                ],
+                'intent': 'Informational'
+            }
+        ]
+    },
+    {
+        'stage': 'Consideration / Research',
+        'goal': 'Compare options, evaluate solutions.',
+        'categories': [
+            {
+                'name': 'Features & Specifications',
+                'description': 'Interest in specific attributes or capabilities.',
+                'keywordPatterns': [
+                    'feature',
+                    'specifications',
+                    'capabilities',
+                    'functions'
+                ],
+                'keywordSeeds': [
+                    'running shoes with arch support',
+                    'CRM with email automation'
+                ],
+                'intent': 'Commercial / Research'
+            },
+            {
+                'name': 'Comparisons',
+                'description': 'Directly comparing brands, products, or categories.',
+                'keywordPatterns': ['vs', 'comparison', 'alternatives', 'best of'],
+                'keywordSeeds': ['Nike vs Adidas', 'HubSpot vs Salesforce'],
+                'intent': 'Commercial / Research'
+            },
+            {
+                'name': 'Suitability & Use Cases',
+                'description': 'Evaluating how well a solution fits specific needs or contexts.',
+                'keywordPatterns': ['best for', 'ideal for', 'use case', 'fit for'],
+                'keywordSeeds': ['best shoes for marathon training', 'CRM for freelancers'],
+                'intent': 'Commercial / Research'
+            },
+            {
+                'name': 'Social Proof & Reviews',
+                'description': 'Looking for recommendations, opinions, ratings, testimonials. Often includes temporal modifiers like "2024".',
+                'keywordPatterns': [
+                    'review',
+                    'rating',
+                    'top-rated',
+                    'best',
+                    'customer feedback'
+                ],
+                'keywordSeeds': ['best CRM software', 'best rated running shoes 2025', 'HubSpot reviews'],
+                'intent': 'Commercial / Research'
+            }
+        ]
+    },
+    {
+        'stage': 'Decision / Evaluation',
+        'goal': 'Prospect is close to acting but still evaluating options.',
+        'categories': [
+            {
+                'name': 'Pricing & Packages',
+                'description': 'Researching cost, plans, discounts, promotions.',
+                'keywordPatterns': [
+                    'price',
+                    'pricing',
+                    'cost',
+                    'plan',
+                    'tier',
+                    'discount'
+                ],
+                'keywordSeeds': ['Nike Pegasus price', 'HubSpot CRM pricing tiers'],
+                'intent': 'Commercial / Research'
+            },
+            {
+                'name': 'Availability & Location',
+                'description': 'Where or how to obtain the product/service.',
+                'keywordPatterns': [
+                    'buy near me',
+                    'availability',
+                    'store',
+                    'online purchase'
+                ],
+                'keywordSeeds': ['buy running shoes near me', 'best CRM free trial'],
+                'intent': 'Commercial / Research'
+            },
+            {
+                'name': 'Intent-to-Act Signals',
+                'description': 'Keywords showing strong intent to act soon but still evaluating options.',
+                'keywordPatterns': [
+                    'sign up trial',
+                    'get started demo',
+                    'order sample',
+                    'try now'
+                ],
+                'keywordSeeds': ['sign up for HubSpot demo', 'get started with CRM trial'],
+                'intent': 'Commercial / Research'
+            }
+        ]
+    },
+    {
+        'stage': 'Conversion / Action',
+        'goal': 'Prospect decides to purchase or take desired action (checkout, demo, signup).',
+        'categories': [
+            {
+                'name': 'Purchase / Signup',
+                'description': 'Final action: completing a purchase, signing up, or starting a trial.',
+                'keywordPatterns': ['buy', 'checkout', 'signup', 'register', 'demo'],
+                'keywordSeeds': ['buy Nike Pegasus online', 'HubSpot CRM demo signup'],
+                'intent': 'Transactional'
+            },
+            {
+                'name': 'Immediate Offers & Promotions',
+                'description': 'Using discounts, coupon codes, or limited-time deals to convert.',
+                'keywordPatterns': [
+                    'discount',
+                    'promo code',
+                    'deal',
+                    'offer',
+                    'coupon'
+                ],
+                'keywordSeeds': ['Nike Pegasus 20% off', 'HubSpot CRM free trial code'],
+                'intent': 'Transactional'
+            }
+        ]
+    },
+    {
+        'stage': 'Post-Purchase / Retention & Advocacy',
+        'goal': 'Support existing customers, encourage loyalty or advocacy.',
+        'categories': [
+            {
+                'name': 'Usage & How-To',
+                'description': 'Guides, tutorials, setup instructions.',
+                'keywordPatterns': [
+                    'how to',
+                    'tutorial',
+                    'setup',
+                    'guide',
+                    'instructions'
+                ],
+                'keywordSeeds': ['how to break in running shoes', 'HubSpot CRM tutorial'],
+                'intent': 'Retention / Post-Purchase'
+            },
+            {
+                'name': 'Troubleshooting & Support',
+                'description': 'Fixing problems, maintenance, FAQs.',
+                'keywordPatterns': ['help', 'troubleshoot', 'issue', 'problem', 'FAQ'],
+                'keywordSeeds': ['Nike Pegasus sizing issues', 'HubSpot login help'],
+                'intent': 'Retention / Post-Purchase'
+            },
+            {
+                'name': 'Upgrades & Add-ons',
+                'description': 'Expanding or enhancing existing purchase.',
+                'keywordPatterns': [
+                    'upgrade',
+                    'add-on',
+                    'extension',
+                    'premium features'
+                ],
+                'keywordSeeds': [
+                    'best insoles for running shoes',
+                    'HubSpot premium features'
+                ],
+                'intent': 'Retention / Post-Purchase'
+            },
+            {
+                'name': 'Community & Advocacy',
+                'description': 'Engagement, referrals, sharing experiences.',
+                'keywordPatterns': [
+                    'forum',
+                    'community',
+                    'refer',
+                    'share',
+                    'testimonial'
+                ],
+                'keywordSeeds': [
+                    'running shoe user forum',
+                    'refer a friend HubSpot discount'
+                ],
+                'intent': 'Retention / Post-Purchase'
+            }
+        ]
+    }
+];
+const CUSTOMIZE_PROMPT = (0, utils_js_1.dedent)(`
+Adapt this marketing funnel for sector '{sector}', market '{market}', language '{language}'.
+{briefing}
+
+RULES:
+1. Keep the same funnel stages (translate names if needed) - only customize categories within stages
+2. Adjust categories to fit the sector: modify names, descriptions, or replace irrelevant ones
+3. "keywordPatterns": Abstract types/themes (e.g., "questions", "comparisons", "pricing")
+4. "keywordSeeds": Real Google searches users actually type - NOT forced combinations of patterns
+   - Think: What would someone naturally search at this stage?
+   - Keep broad (1-3 words) to seed Google Keyword Planner for 100s-1000s of ideas
+   - Generate 3-10 keywordSeeds per category
+5. Patterns and keywordSeeds should align thematically but DON'T force pattern words into keywordSeeds. Focus on the category "description" to guide relevant keywordSeeds.
+
+Example for running shoes:
+- Category description: "Palabras clave que muestran alta intención de compra, aunque todavía evaluando la mejor opción",
+- Keyword Patterns: ["probar", "reservar", "solicitar prueba", "más info"]
+- GOOD keywordSeeds: ["elegir talla zapatilla", "analisis de pisada"]
+  BAD: ["probar zapatillas", "reservar zapatillas"] (unnatural search)
+- Pattern: ["comparativas"] → KeywordSeeds: ["nike vs adidas", "mejores zapatillas 2025"]
+
+Return the customized funnel in language {userLanguage} except keywordSeeds, that should maintain the original language.
+
+Also provide an "explanation" field with a brief summary (2-3 sentences) explaining the reasoning behind
+the funnel customization: how the stages and categories were adapted for this sector and market,
+and what customer journey they represent.
+
+{instructions}
+
+# Generic funnel structure
+
+{funnel}
+`);
+/**
+ * Customize a generic marketing funnel to a specific sector and market using an LLM.
+ */
+async function customizeFunnel(sector, language, userLanguage = null, country = 'global', briefing = null, instructions = null, model = 'gpt-4.1', funnel = { stages: GENERIC_FUNNEL }) {
+    const funnelData = Array.isArray(funnel) ? funnel : funnel.stages;
+    const prompt = CUSTOMIZE_PROMPT
+        .replace('{sector}', sector)
+        .replace('{briefing}', briefing || '')
+        .replace('{instructions}', instructions || '')
+        .replace('{market}', country)
+        .replace('{language}', language)
+        .replace('{userLanguage}', userLanguage ?? language)
+        .replace('{funnel}', JSON.stringify(funnelData, null, 2));
+    const { parsed } = await (0, openai_js_1.askOpenAISafe)(prompt, model, funnel_schema_js_1.FunnelWithExplanationSchema);
+    if (!parsed) {
+        throw new Error('Failed to parse response from OpenAI');
+    }
+    return parsed;
+}
+const GENERATE_SEEDS_PROMPT = (0, utils_js_1.dedent)(`
+Generate 3-10 Google search keywords that real users type when researching {sector} at this funnel stage.
+
+Stage: {stage} ({goal})
+Category: {category} - {description}
+Intent: {intent}
+Theme indicators: {patterns}
+
+CRITICAL: Generate what people ACTUALLY search, NOT literal combinations of theme words.
+
+Example for running shoes / "Señales de Intención" / themes ["probar", "reservar"]:
+✅ GOOD: "elegir talla zapatilla", "analisis de pisada"
+❌ BAD: "probar zapatillas", "reservar zapatillas" (unnatural, nobody searches this)
+
+Requirements:
+- Broad queries (1-3 words) suitable for Google Keyword Planner seed expansion
+- Natural language people actually type in search bars
+- Match the stage intent and category purpose
+- Output {language} for {market} market
+- 5-10 keywords (more is better)
+
+What would someone in {market} naturally search when {description}?
+`);
+/**
+ * Generate example seed keywords for a specific funnel category using an LLM.
+ */
+async function generateSeedKeywords(stage, goal, category, sector, language, country = 'global', model = 'gpt-4.1') {
+    const prompt = GENERATE_SEEDS_PROMPT
+        .replace('{stage}', stage)
+        .replace('{goal}', goal)
+        .replace('{category}', category.name)
+        .replace('{description}', category.description)
+        .replace('{intent}', category.intent)
+        .replace('{patterns}', category.keywordPatterns.join(', '))
+        .replace('{sector}', sector)
+        .replace('{market}', country)
+        .replace('{language}', language);
+    const { parsed } = await (0, openai_js_1.askOpenAISafe)(prompt, model, funnel_schema_js_1.SeedsSchema);
+    if (!parsed) {
+        throw new Error('Failed to parse seed keywords from OpenAI');
+    }
+    return parsed.seeds;
+}
+/**
+ * Regenerates seed keywords for all categories in a funnel concurrently,
+ * updating the keywordSeeds field in-place for each category.
+ */
+async function reseedFunnel(funnel, sector, language, country = 'global', model = 'gpt-4.1', maxConcurrency = 100) {
+    const categories = [];
+    for (const categoryTuple of iterateFunnelCategories(funnel)) {
+        categories.push(categoryTuple);
+    }
+    await (0, async_js_1.mapParallel)(categories, maxConcurrency, async ([stage, goal, category]) => {
+        const seeds = await generateSeedKeywords(stage, goal, category, sector, language, country, model);
+        category.keywordSeeds = seeds;
+    });
+    if (Array.isArray(funnel)) {
+        return { stages: funnel, explanation: '' };
+    }
+    return funnel;
+}
+/**
+ * Generate a complete customized marketing funnel with seed keywords.
+ * This is a convenience wrapper that combines customizeFunnel and reseedFunnel.
+ */
+async function generateFunnel({ sector, language, userLanguage, country, model, funnel, briefing, maxConcurrency, instructions }) {
+    const customized = await customizeFunnel(sector, language, userLanguage, country || 'global', briefing, instructions, model || 'gpt-4.1', funnel || { stages: GENERIC_FUNNEL });
+    const reseeded = await reseedFunnel(customized, sector, language, country || 'global', model || 'gpt-4.1', maxConcurrency ?? 100);
+    return reseeded;
+}

package/script/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/script/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/script/src/tools/keywords.js

@@ -0,0 +1,190 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expandKeywords = expandKeywords;
+exports.generateKeywords = generateKeywords;
+const async_js_1 = require("../async.js");
+const openai_js_1 = require("../openai.js");
+const brands_js_1 = require("./brands.js");
+const keyword_schema_js_1 = require("../schemas/keyword.schema.js");
+const utils_js_1 = require("../utils.js");
+const keywordPlanner_js_1 = require("../apis/googleAds/keywordPlanner.js");
+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 = (0, async_js_1.mapParallel)(seedKeywords, 2, async (keyword) => {
+        const keywordData = await (0, keywordPlanner_js_1.keywords)({
+            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
+        ? (0, keywordPlanner_js_1.keywords)({
+            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 = (0, utils_js_1.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 = (0, utils_js_1.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 = (0, utils_js_1.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 = (0, utils_js_1.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 = (0, utils_js_1.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.
+`);
+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 = (0, brands_js_1.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 (0, openai_js_1.askOpenAISafe)(content, model, keyword_schema_js_1.KeywordsResponseSchema);
+    if (!parsed) {
+        throw new Error('Failed to parse response from OpenAI');
+    }
+    return parsed;
+}
+__exportStar(require("../schemas/keyword.schema.js"), exports);

package/script/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/script/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"}