@synterai/sdk-js 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1260 @@
+/**
+ * Shared enums for the typed tool methods, matching catalog.json's
+ * `platforms` list and the `date_range` enum used by `get_performance`.
+ *
+ * Kept distinct from the legacy `Platform` type in `../types` (which only
+ * covers google/reddit/x for click-ID/UTM macro purposes and is used by
+ * `../utils/*`) to avoid narrowing that unrelated, pre-existing surface.
+ */
+type AdPlatform = 'google' | 'meta' | 'linkedin' | 'microsoft' | 'reddit' | 'tiktok' | 'x';
+type DateRange = 'TODAY' | 'YESTERDAY' | 'LAST_7_DAYS' | 'LAST_30_DAYS' | 'THIS_MONTH' | 'LAST_MONTH';
+
+/**
+ * `campaigns` category — catalog.json tools: list_campaigns,
+ * create_search_campaign, create_display_campaign, create_pmax_campaign,
+ * pause_campaign, update_campaign_budget.
+ */
+
+interface ListCampaignsInput {
+    /**
+     * Filter by platform (optional - lists all if not specified).
+     *
+     * NOTE (preserved per SPEC.md/catalog.json dispatch note): an omitted
+     * platform only queries Google, not all connected platforms, despite
+     * the tool's description — this mirrors confirmed production behavior.
+     */
+    platform?: AdPlatform;
+    /** Filter by campaign status. */
+    status?: 'ENABLED' | 'PAUSED' | 'REMOVED';
+    /** Maximum number of campaigns to return (default: 50). */
+    limit?: number;
+}
+interface CreateSearchCampaignInput {
+    /** Name for the campaign. */
+    campaign_name: string;
+    /** Daily budget in USD. */
+    daily_budget: number;
+    /** Keywords to target (phrase match). Minimum 1. */
+    keywords: string[];
+    /** Headlines, 3-15, max 30 chars each. */
+    headlines: string[];
+    /** Descriptions, 2-4, max 90 chars each. */
+    descriptions: string[];
+    /** Landing page URL. */
+    final_url: string;
+    /** Geo target codes (e.g. '2840' for US). */
+    geo_targets?: string[];
+}
+interface CreateDisplayCampaignInput {
+    campaign_name: string;
+    /** Daily budget in USD. */
+    daily_budget: number;
+    /** Headlines (1-5, max 30 chars each). */
+    headlines: string[];
+    /** Descriptions (1-5, max 90 chars each). */
+    descriptions: string[];
+    /** Business name (max 25 chars). */
+    business_name: string;
+    /** Landing page URL. */
+    final_url: string;
+    /**
+     * URL to 1200x628 landscape image.
+     *
+     * KNOWN ISSUE (SPEC.md "Known issues" #3): Display and PMax use
+     * inconsistent flag names for the same concept — this sends
+     * `--landscape-image`, while `create_pmax_campaign` sends
+     * `--landscape-image-url` for the equivalent field. Preserved verbatim
+     * so calls actually work against the real backend scripts.
+     */
+    landscape_image_url?: string;
+    /** URL to 1200x1200 square image. See known-issue note above (`--square-image`, not `-url`). */
+    square_image_url?: string;
+    geo_targets?: string[];
+}
+interface CreatePmaxCampaignInput {
+    campaign_name: string;
+    daily_budget: number;
+    /** Headlines (3-15, max 30 chars each). */
+    headlines: string[];
+    /** Long headline (max 90 chars). */
+    long_headline: string;
+    /** Descriptions (2-5, max 90 chars each). */
+    descriptions: string[];
+    /** Business name (max 25 chars). */
+    business_name: string;
+    final_url: string;
+    /** See known-issue note on {@link CreateDisplayCampaignInput.landscape_image_url} — this uses `--landscape-image-url`. */
+    landscape_image_url?: string;
+    square_image_url?: string;
+    /** URL to square logo (min 128x128). */
+    logo_url?: string;
+    geo_targets?: string[];
+    /** Target CPA in USD (optional). */
+    target_cpa?: number;
+}
+interface PauseCampaignInput {
+    /** Campaign ID (platform-specific format). */
+    campaign_id: string;
+    /**
+     * KNOWN ISSUE (SPEC.md "Known issues" #1, catalog.json `knownIssues`):
+     * the schema requires/accepts this field for all 7 platforms and the
+     * tool description claims cross-platform support, but live dispatch
+     * hardcodes `platform=google` regardless of what's passed here.
+     * Preserved verbatim — flagged to Joel as a product bug, not "fixed"
+     * in the SDK.
+     */
+    platform: AdPlatform;
+}
+interface UpdateCampaignBudgetInput {
+    campaign_id: string;
+    /** See {@link PauseCampaignInput.platform} — same known issue: ignored, live dispatch always sends `platform=google`. */
+    platform: AdPlatform;
+    /** New daily budget in USD. */
+    daily_budget: number;
+}
+declare class CampaignsResource {
+    private readonly client;
+    constructor(client: Synter);
+    /**
+     * List all campaigns across connected ad platforms. Returns campaign
+     * name, status, budget, and performance metrics.
+     *
+     * Custom-dispatch tool (platform-routed script name) — see SPEC.md's
+     * "Platform resolution" rule 2 and the note on {@link ListCampaignsInput.platform}.
+     */
+    list(input?: ListCampaignsInput): Promise<Record<string, unknown>>;
+    /**
+     * Create a Google Ads Search campaign with an ad group, responsive
+     * search ad, and keywords — all in one atomic request. Requires at
+     * least 3 headlines (max 30 chars) and 2 descriptions (max 90 chars).
+     */
+    createSearch(input: CreateSearchCampaignInput): Promise<Record<string, unknown>>;
+    /**
+     * Create a Google Ads Display campaign with responsive display ads.
+     * Supports image uploads from URLs.
+     */
+    createDisplay(input: CreateDisplayCampaignInput): Promise<Record<string, unknown>>;
+    /**
+     * Create a Google Ads Performance Max campaign. Requires images,
+     * headlines, descriptions, and a business name.
+     */
+    createPmax(input: CreatePmaxCampaignInput): Promise<Record<string, unknown>>;
+    /**
+     * Pause a campaign by ID.
+     *
+     * KNOWN ISSUE: see {@link PauseCampaignInput.platform} — always
+     * dispatches with `platform=google` regardless of input.
+     */
+    pause(input: PauseCampaignInput): Promise<Record<string, unknown>>;
+    /**
+     * Update the daily budget for a campaign.
+     *
+     * KNOWN ISSUE: see {@link UpdateCampaignBudgetInput.platform} — always
+     * dispatches with `platform=google` regardless of input.
+     */
+    updateBudget(input: UpdateCampaignBudgetInput): Promise<Record<string, unknown>>;
+}
+
+/**
+ * `analytics` category — catalog.json tools: get_performance, get_daily_spend.
+ *
+ * Both are custom-dispatch per SPEC.md's testing bar (not forced through
+ * the generic argMapping-only path): get_performance has a platform-scoped
+ * `onlyForPlatform` flag and a `dateRangeToDays` transform; get_daily_spend
+ * has a fixed script name but still resolves/sends a platform, and (unlike
+ * any other tool) also re-emits that resolved platform as an uppercased
+ * CLI flag.
+ */
+
+interface GetPerformanceInput {
+    /** Filter by platform (optional). */
+    platform?: AdPlatform;
+    /** Filter by specific campaign ID (optional). Only forwarded when the resolved platform is `google` — see known-supported note above. */
+    campaign_id?: string;
+    /** Date range for metrics (default: LAST_7_DAYS). */
+    date_range?: DateRange;
+}
+interface GetDailySpendInput {
+    /** Number of days to look back (default: 7). */
+    days?: number;
+    platform?: AdPlatform;
+}
+declare class AnalyticsResource {
+    private readonly client;
+    constructor(client: Synter);
+    /**
+     * Get performance metrics (impressions, clicks, spend, conversions,
+     * ROAS) for campaigns.
+     */
+    getPerformance(input?: GetPerformanceInput): Promise<Record<string, unknown>>;
+    /** Get daily spend breakdown across all connected ad accounts. */
+    getDailySpend(input?: GetDailySpendInput): Promise<Record<string, unknown>>;
+}
+
+/**
+ * `keywords` category — catalog.json tools: add_keywords, add_negative_keywords.
+ * Both fixed to `platform: "google"` (no cross-platform keyword scripts exist yet).
+ */
+
+interface AddKeywordsInput {
+    ad_group_id: string;
+    keywords: string[];
+    /** default: PHRASE */
+    match_type?: 'EXACT' | 'PHRASE' | 'BROAD';
+}
+interface AddNegativeKeywordsInput {
+    campaign_id: string;
+    keywords: string[];
+    /** default: CAMPAIGN */
+    level?: 'CAMPAIGN' | 'AD_GROUP';
+}
+declare class KeywordsResource {
+    private readonly client;
+    constructor(client: Synter);
+    /** Add keywords to a Google Ads campaign or ad group. */
+    add(input: AddKeywordsInput): Promise<Record<string, unknown>>;
+    /** Add negative keywords to block unwanted search terms. */
+    addNegative(input: AddNegativeKeywordsInput): Promise<Record<string, unknown>>;
+}
+
+/**
+ * `conversions` category — catalog.json tools: create_conversion,
+ * list_conversions, diagnose_tracking.
+ */
+
+interface CreateConversionInput {
+    /** e.g. 'Signup', 'Purchase' */
+    name: string;
+    /** Default conversion value in USD (optional). */
+    value?: number;
+    /** default: LEAD */
+    category?: 'PURCHASE' | 'SIGNUP' | 'LEAD' | 'PAGE_VIEW' | 'ADD_TO_CART' | 'DOWNLOAD' | 'OTHER';
+}
+interface DiagnoseTrackingInput {
+    /** Website URL to check. */
+    url: string;
+}
+declare class ConversionsResource {
+    private readonly client;
+    constructor(client: Synter);
+    /**
+     * Create a conversion action in Google Ads. Returns the conversion ID
+     * and label for GTM setup.
+     */
+    create(input: CreateConversionInput): Promise<Record<string, unknown>>;
+    /** List all conversion actions configured in Google Ads. */
+    list(): Promise<Record<string, unknown>>;
+    /**
+     * Check if conversion tracking is properly set up on a website.
+     * Verifies gtag.js, GTM, and pixel installation.
+     *
+     * No platform is sent for this tool — it isn't tied to ad-account
+     * credentials (SPEC.md's "Platform resolution" rule 3).
+     */
+    diagnoseTracking(input: DiagnoseTrackingInput): Promise<Record<string, unknown>>;
+}
+
+/**
+ * `creative` category — catalog.json tools: generate_image, generate_video.
+ * Neither is tied to a platform's OAuth credentials (SPEC.md's "Platform
+ * resolution" rule 3 — no `platform` key at all).
+ */
+
+interface GenerateImageInput {
+    /** Be specific about style, layout, colors. */
+    prompt: string;
+    /** default: 1200x628 */
+    size?: '1200x628' | '1200x1200' | '1080x1080' | '1920x1080';
+    /** default: imagen */
+    provider?: 'imagen' | 'flux' | 'sdxl';
+    /** Asset name for organization. */
+    name?: string;
+}
+interface GenerateVideoInput {
+    product_name: string;
+    /** Main value proposition. */
+    key_benefit: string;
+    /** default: pas */
+    concept?: 'pas' | 'aida' | 'before_after' | 'testimonial' | 'demo' | 'execute';
+    target_audience?: string;
+    /** default: 8 */
+    duration?: 6 | 8 | 15 | 30;
+    /** default: veo */
+    provider?: 'veo' | 'runway' | 'luma' | 'creatify';
+}
+declare class CreativeResource {
+    private readonly client;
+    constructor(client: Synter);
+    /** Generate an AI image for ad creatives using Imagen 4, Flux, or Stable Diffusion. */
+    generateImage(input: GenerateImageInput): Promise<Record<string, unknown>>;
+    /** Generate an AI video ad using Veo, Runway, or Luma. Great for YouTube and social ads. */
+    generateVideo(input: GenerateVideoInput): Promise<Record<string, unknown>>;
+}
+
+/**
+ * `meta` category — catalog.json tool: create_meta_campaign.
+ * One method today; kept in its own namespace so more can be added later
+ * without renaming, per SPEC.md's naming table.
+ */
+
+interface CreateMetaCampaignInput {
+    name: string;
+    objective: 'CONVERSIONS' | 'TRAFFIC' | 'LEADS' | 'AWARENESS' | 'ENGAGEMENT';
+    daily_budget: number;
+}
+declare class MetaResource {
+    private readonly client;
+    constructor(client: Synter);
+    /** Create a Meta (Facebook/Instagram) advertising campaign. */
+    createCampaign(input: CreateMetaCampaignInput): Promise<Record<string, unknown>>;
+}
+
+/**
+ * `linkedin` category — catalog.json tool: create_linkedin_campaign.
+ * One method today; kept in its own namespace so more can be added later
+ * without renaming, per SPEC.md's naming table.
+ */
+
+interface CreateLinkedInCampaignInput {
+    name: string;
+    objective: 'WEBSITE_VISIT' | 'LEAD_GENERATION' | 'ENGAGEMENT' | 'VIDEO_VIEW' | 'BRAND_AWARENESS';
+    daily_budget: number;
+    target_company_sizes?: ('1-10' | '11-50' | '51-200' | '201-500' | '501-1000' | '1001-5000' | '5001-10000' | '10001+')[];
+    target_industries?: string[];
+    target_job_functions?: string[];
+}
+declare class LinkedInResource {
+    private readonly client;
+    constructor(client: Synter);
+    /** Create a LinkedIn Ads campaign for B2B advertising. */
+    createCampaign(input: CreateLinkedInCampaignInput): Promise<Record<string, unknown>>;
+}
+
+/**
+ * `reddit` category — catalog.json tool: create_reddit_campaign.
+ * One method today; kept in its own namespace so more can be added later
+ * without renaming, per SPEC.md's naming table.
+ */
+
+interface CreateRedditCampaignInput {
+    name: string;
+    objective: 'TRAFFIC' | 'CONVERSIONS' | 'VIDEO_VIEWS' | 'APP_INSTALLS' | 'REACH';
+    daily_budget: number;
+    /** Optional - omit for interest-based targeting. */
+    subreddits?: string[];
+    interests?: string[];
+}
+declare class RedditResource {
+    private readonly client;
+    constructor(client: Synter);
+    /** Create a Reddit Ads campaign for community-based advertising. */
+    createCampaign(input: CreateRedditCampaignInput): Promise<Record<string, unknown>>;
+}
+
+/**
+ * `audiences` category — catalog.json tools: stage_audience_artifact
+ * (custom handler, special endpoint), sync_audience (custom handler,
+ * argBuildingRules), manage_audience (generic argMapping).
+ */
+
+interface StageAudienceArtifactInput {
+    /** Newline-delimited identifiers. SHA-256 hex for emails/phones; raw uppercase UUIDs for MAIDs. */
+    body: string;
+    /** Which script will consume this artifact. Default 'meta_ads_create_audience'. */
+    script_name?: string;
+    /** Default 3600 (1 hour). */
+    ttl_seconds?: number;
+    /** Confirm lawful basis under GDPR/CCPA + platform terms for every identifier. Omitting logs a warning (soft-launch). */
+    i_have_consent?: boolean;
+}
+interface StageAudienceArtifactResult {
+    artifact_id: string;
+    [key: string]: unknown;
+}
+interface SyncAudienceInput {
+    platform: AdPlatform;
+    audience_name?: string;
+    /** Optional — defaults to the user's primary account on that platform. */
+    account_id?: string;
+    /** Comma-separated SHA-256 hashed emails, lowercase hex. */
+    hashed_emails?: string;
+    hashed_emails_artifact_id?: string;
+    /** Comma-separated SHA-256 hashed phones (E.164 pre-hash). */
+    hashed_phones?: string;
+    /** Meta + most platforms; not supported by Google's customer match script today. */
+    hashed_phones_artifact_id?: string;
+    /** Comma-separated raw IDFA/GAID, uppercase UUID. Meta and TikTok only. NOT hashed. */
+    mobile_ids?: string;
+    /** Meta only. */
+    mobile_ids_artifact_id?: string;
+    /** B2B account targeting (Google + LinkedIn). */
+    company_domains?: string;
+    csv_url?: string;
+    /** Meta only: USER_PROVIDED_ONLY (default), PARTNER_PROVIDED_ONLY, or BOTH_USER_AND_PARTNER_PROVIDED. */
+    customer_file_source?: 'USER_PROVIDED_ONLY' | 'PARTNER_PROVIDED_ONLY' | 'BOTH_USER_AND_PARTNER_PROVIDED';
+    i_have_consent?: boolean;
+}
+interface ManageAudienceInput {
+    action: 'create' | 'upload' | 'list' | 'status' | 'list-sources';
+    /** Required for action=create. Required for action=upload unless audience_id is provided. */
+    name?: string;
+    /** Comma-separated, hashed client-side before upload. */
+    emails?: string;
+    /** Comma-separated, E.164 format. */
+    phones?: string;
+    company_domains?: string;
+    /** Alternative to name for action=upload. */
+    audience_id?: string;
+    /** Days to keep members; default 540, max 540. */
+    membership_lifespan?: number;
+    /** Required for action=status. */
+    job_resource_name?: string;
+}
+declare class AudiencesResource {
+    private readonly client;
+    constructor(client: Synter);
+    /**
+     * Stage a hashed-PII payload (newline-delimited identifiers — SHA-256
+     * emails, phones, or raw MAIDs) in Synter's private artifact store and
+     * return an opaque `artifact_id`. Pass that id to `sync()` via
+     * `*_artifact_id` parameters. FREE. Use instead of pasting hashed
+     * identifiers inline when over ~500 entries.
+     *
+     * Bypasses the primary `tools/run` dispatcher: different host
+     * (`https://api.syntermedia.ai`) and a different auth header
+     * (`X-Synter-Key`, not `Authorization: Bearer`) — see SPEC.md/catalog.json
+     * `transport.special`.
+     */
+    stageArtifact(input: StageAudienceArtifactInput): Promise<StageAudienceArtifactResult>;
+    /**
+     * Upload an audience to an ad platform. Accepts inline hashed
+     * identifiers, raw mobile_ids, company_domains, a public csv_url, or
+     * `*_artifact_id` references staged via `stageArtifact()`. Costs 10
+     * credits on success.
+     *
+     * Custom handler per catalog.json's `dispatch.argBuildingRules` — does
+     * not go through the generic argMapping path.
+     */
+    sync(input: SyncAudienceInput): Promise<Record<string, unknown>>;
+    /**
+     * Create, upload to, or list first-party audiences in Google Ads via
+     * the Data Manager API. Supports Customer Match lists from emails,
+     * phone numbers, and company domains.
+     */
+    manage(input: ManageAudienceInput): Promise<Record<string, unknown>>;
+}
+
+/**
+ * Amp Custom Advertising Toolbox
+ *
+ * A collection of AI-powered advertising tools specifically designed for
+ * Amp integration, providing intelligent campaign management, creative
+ * generation, and optimization capabilities.
+ */
+
+interface AmpToolboxConfig {
+    /**
+     * AI model to use for creative generation
+     * @default 'gpt-4'
+     */
+    aiModel?: 'gpt-4' | 'gpt-4-turbo' | 'gpt-3.5-turbo';
+    /**
+     * Enable auto-optimization
+     * @default true
+     */
+    autoOptimize?: boolean;
+    /**
+     * Optimization interval in hours
+     * @default 24
+     */
+    optimizeInterval?: number;
+    /**
+     * Enable A/B testing
+     * @default true
+     */
+    enableABTesting?: boolean;
+}
+interface CampaignBriefInput {
+    /**
+     * Business/product description
+     */
+    product: string;
+    /**
+     * Target audience description
+     */
+    audience: string;
+    /**
+     * Campaign goals (awareness, conversions, engagement)
+     */
+    goals: string[];
+    /**
+     * Budget constraints
+     */
+    budget: {
+        total: number;
+        currency: string;
+    };
+    /**
+     * Preferred platforms
+     */
+    platforms?: ('google' | 'reddit' | 'x' | 'linkedin')[];
+    /**
+     * Brand voice/tone
+     */
+    brandVoice?: string;
+    /**
+     * Competitive context
+     */
+    competitors?: string[];
+}
+interface GeneratedCampaign {
+    /**
+     * Campaign strategy overview
+     */
+    strategy: string;
+    /**
+     * Recommended budget allocation
+     */
+    budgetAllocation: {
+        platform: string;
+        amount: number;
+        percentage: number;
+    }[];
+    /**
+     * Generated ad creatives
+     */
+    creatives: {
+        platform: string;
+        headlines: string[];
+        descriptions: string[];
+        callsToAction: string[];
+        keywords?: string[];
+    }[];
+    /**
+     * Targeting recommendations
+     */
+    targeting: {
+        platform: string;
+        keywords?: string[];
+        interests?: string[];
+        demographics?: any;
+        locations?: string[];
+    }[];
+    /**
+     * Success metrics to track
+     */
+    kpis: {
+        metric: string;
+        target: number;
+        threshold: number;
+    }[];
+}
+interface OptimizationRecommendation {
+    /**
+     * Campaign ID
+     */
+    campaignId: string;
+    /**
+     * Type of optimization
+     */
+    type: 'budget' | 'creative' | 'targeting' | 'bidding';
+    /**
+     * Current performance
+     */
+    current: {
+        metric: string;
+        value: number;
+    };
+    /**
+     * Recommended action
+     */
+    recommendation: string;
+    /**
+     * Expected impact
+     */
+    expectedImpact: {
+        metric: string;
+        change: number;
+        changePercent: number;
+    };
+    /**
+     * Confidence score (0-1)
+     */
+    confidence: number;
+    /**
+     * Reasoning
+     */
+    reasoning: string;
+}
+interface CreativeVariant {
+    /**
+     * Variant ID
+     */
+    id: string;
+    /**
+     * Creative content
+     */
+    headline: string;
+    description: string;
+    callToAction: string;
+    /**
+     * Performance metrics (if tested)
+     */
+    performance?: {
+        impressions: number;
+        clicks: number;
+        ctr: number;
+        conversions: number;
+        cost: number;
+    };
+}
+/**
+ * Amp Advertising Toolbox
+ *
+ * Provides AI-powered tools for campaign creation, optimization, and creative generation
+ */
+declare class AmpToolbox {
+    private client;
+    private config;
+    constructor(client: Synter, config?: AmpToolboxConfig);
+    /**
+     * Generate a complete campaign from a brief description
+     *
+     * @example
+     * ```ts
+     * const campaign = await amp.generateCampaign({
+     *   product: 'AI-powered email marketing platform',
+     *   audience: 'SaaS marketers, 25-45, tech-savvy',
+     *   goals: ['lead-generation', 'brand-awareness'],
+     *   budget: { total: 10000, currency: 'USD' },
+     *   platforms: ['google', 'linkedin'],
+     *   brandVoice: 'professional, innovative, data-driven'
+     * });
+     * ```
+     */
+    generateCampaign(brief: CampaignBriefInput): Promise<GeneratedCampaign>;
+    /**
+     * Generate creative variations for A/B testing
+     *
+     * @example
+     * ```ts
+     * const variants = await amp.generateCreativeVariants({
+     *   baseCreative: {
+     *     headline: 'Transform Your Email Marketing',
+     *     description: 'AI-powered automation for better results'
+     *   },
+     *   count: 5,
+     *   platform: 'google'
+     * });
+     * ```
+     */
+    generateCreativeVariants(options: {
+        baseCreative?: {
+            headline?: string;
+            description?: string;
+            callToAction?: string;
+        };
+        productDescription?: string;
+        count: number;
+        platform: 'google' | 'reddit' | 'x' | 'linkedin';
+        tone?: 'professional' | 'casual' | 'urgent' | 'friendly';
+    }): Promise<CreativeVariant[]>;
+    /**
+     * Analyze campaign performance and get AI-powered optimization recommendations
+     *
+     * @example
+     * ```ts
+     * const recommendations = await amp.getOptimizationRecommendations({
+     *   campaignIds: ['cmp_123', 'cmp_456'],
+     *   window: '7d',
+     *   minConfidence: 0.7
+     * });
+     * ```
+     */
+    getOptimizationRecommendations(options: {
+        campaignIds?: string[];
+        window?: string;
+        minConfidence?: number;
+    }): Promise<OptimizationRecommendation[]>;
+    /**
+     * Auto-optimize campaigns based on performance data
+     *
+     * @example
+     * ```ts
+     * const result = await amp.autoOptimize({
+     *   campaignIds: ['cmp_123'],
+     *   dryRun: true, // Preview changes first
+     *   optimizationTypes: ['budget', 'bidding']
+     * });
+     * ```
+     */
+    autoOptimize(options: {
+        campaignIds?: string[];
+        dryRun?: boolean;
+        optimizationTypes?: ('budget' | 'creative' | 'targeting' | 'bidding')[];
+        minConfidence?: number;
+    }): Promise<{
+        appliedOptimizations: OptimizationRecommendation[];
+        skippedOptimizations: OptimizationRecommendation[];
+        dryRun: boolean;
+    }>;
+    /**
+     * Generate keyword suggestions based on product/service
+     *
+     * @example
+     * ```ts
+     * const keywords = await amp.generateKeywords({
+     *   product: 'AI email marketing platform',
+     *   audience: 'SaaS marketers',
+     *   count: 50
+     * });
+     * ```
+     */
+    generateKeywords(options: {
+        product: string;
+        audience?: string;
+        competitors?: string[];
+        count?: number;
+    }): Promise<{
+        keywords: Array<{
+            keyword: string;
+            intent: 'commercial' | 'informational' | 'transactional';
+            estimatedVolume?: number;
+            competition?: 'low' | 'medium' | 'high';
+            relevanceScore: number;
+        }>;
+    }>;
+    /**
+     * Analyze competitor ads and get insights
+     *
+     * @example
+     * ```ts
+     * const analysis = await amp.analyzeCompetitors({
+     *   competitors: ['competitor1.com', 'competitor2.com'],
+     *   industry: 'SaaS'
+     * });
+     * ```
+     */
+    analyzeCompetitors(options: {
+        competitors: string[];
+        industry?: string;
+    }): Promise<{
+        competitors: Array<{
+            name: string;
+            url: string;
+            adStrategies: string[];
+            messaging: string[];
+            strengths: string[];
+            weaknesses: string[];
+        }>;
+        opportunities: string[];
+        threats: string[];
+        recommendations: string[];
+    }>;
+    /**
+     * Create an A/B test for campaign creatives
+     *
+     * @example
+     * ```ts
+     * const test = await amp.createABTest({
+     *   campaignId: 'cmp_123',
+     *   variants: [
+     *     { headline: 'Version A', description: 'Test A' },
+     *     { headline: 'Version B', description: 'Test B' }
+     *   ],
+     *   trafficSplit: [50, 50],
+     *   duration: '7d'
+     * });
+     * ```
+     */
+    createABTest(options: {
+        campaignId: string;
+        variants: Array<{
+            headline: string;
+            description: string;
+            callToAction?: string;
+        }>;
+        trafficSplit?: number[];
+        duration?: string;
+        successMetric?: 'ctr' | 'conversions' | 'cpa' | 'roas';
+    }): Promise<{
+        testId: string;
+        status: 'running' | 'scheduled';
+        variants: CreativeVariant[];
+        startDate: string;
+        endDate: string;
+    }>;
+    /**
+     * Get A/B test results and winner
+     *
+     * @example
+     * ```ts
+     * const results = await amp.getABTestResults('test_123');
+     * ```
+     */
+    getABTestResults(testId: string): Promise<{
+        testId: string;
+        status: 'running' | 'completed' | 'inconclusive';
+        variants: CreativeVariant[];
+        winner?: {
+            variantId: string;
+            confidence: number;
+            improvement: number;
+        };
+        recommendations: string[];
+    }>;
+    /**
+     * Generate audience personas based on campaign data
+     *
+     * @example
+     * ```ts
+     * const personas = await amp.generatePersonas({
+     *   campaignIds: ['cmp_123'],
+     *   count: 3
+     * });
+     * ```
+     */
+    generatePersonas(options: {
+        campaignIds?: string[];
+        product?: string;
+        industry?: string;
+        count?: number;
+    }): Promise<{
+        personas: Array<{
+            name: string;
+            demographics: {
+                age: string;
+                gender?: string;
+                location?: string;
+                income?: string;
+            };
+            psychographics: {
+                interests: string[];
+                values: string[];
+                painPoints: string[];
+            };
+            behavior: {
+                platforms: string[];
+                contentPreferences: string[];
+                purchaseDrivers: string[];
+            };
+            messagingTips: string[];
+        }>;
+    }>;
+    /**
+     * Predict campaign performance before launch
+     *
+     * @example
+     * ```ts
+     * const prediction = await amp.predictPerformance({
+     *   platform: 'google',
+     *   budget: { daily: 100, total: 3000 },
+     *   targeting: { keywords: ['email marketing', 'automation'] },
+     *   creative: { headline: 'Transform Your Email Marketing' }
+     * });
+     * ```
+     */
+    predictPerformance(options: {
+        platform: string;
+        budget: {
+            daily?: number;
+            total: number;
+        };
+        targeting: any;
+        creative: {
+            headline: string;
+            description?: string;
+        };
+    }): Promise<{
+        estimatedMetrics: {
+            impressions: {
+                min: number;
+                max: number;
+                expected: number;
+            };
+            clicks: {
+                min: number;
+                max: number;
+                expected: number;
+            };
+            conversions: {
+                min: number;
+                max: number;
+                expected: number;
+            };
+            cpa: {
+                min: number;
+                max: number;
+                expected: number;
+            };
+        };
+        confidence: number;
+        recommendations: string[];
+    }>;
+    /**
+     * Get intelligent budget allocation across platforms
+     *
+     * @example
+     * ```ts
+     * const allocation = await amp.optimizeBudgetAllocation({
+     *   totalBudget: 10000,
+     *   platforms: ['google', 'linkedin', 'reddit'],
+     *   goal: 'conversions'
+     * });
+     * ```
+     */
+    optimizeBudgetAllocation(options: {
+        totalBudget: number;
+        platforms: string[];
+        goal: 'conversions' | 'awareness' | 'engagement' | 'revenue';
+        constraints?: {
+            minPerPlatform?: number;
+            maxPerPlatform?: number;
+        };
+    }): Promise<{
+        allocation: Array<{
+            platform: string;
+            amount: number;
+            percentage: number;
+            expectedROI: number;
+            reasoning: string;
+        }>;
+        totalBudget: number;
+        expectedOverallROI: number;
+    }>;
+}
+
+/**
+ * Error types for @synterai/sdk-js
+ *
+ * Per SPEC.md's "Error model" section: every SDK exposes one error type
+ * carrying `message`, `status`, `code`, and `details`, plus a distinct,
+ * clearly-named error for client-side validation failures (caught before
+ * any network call) so callers can tell "I called it wrong" apart from
+ * "the API rejected it" apart from "the network failed".
+ */
+/**
+ * Raised for any non-2xx response from the Synter API, and for network
+ * failures that exhaust the retry budget (in which case `status` is `0`,
+ * per SPEC.md's error model: "0 or absent for network-level failures").
+ */
+declare class SynterError extends Error {
+    /** HTTP status code; `0` for network-level failures. */
+    readonly status: number;
+    /** Machine-readable error code from the response body, when present. */
+    readonly code: string | null;
+    /** Additional structured error detail from the response body, when present. */
+    readonly details: Record<string, unknown> | null;
+    constructor(message: string, status?: number, code?: string | null, details?: Record<string, unknown> | null);
+}
+/**
+ * Raised when a required field is missing (or malformed) for a tool call,
+ * caught client-side before any network request is made. Distinct from
+ * {@link SynterError} so callers can tell a bad call apart from a rejected
+ * or failed one.
+ */
+declare class SynterValidationError extends Error {
+    /** The input field that failed validation, when applicable. */
+    readonly field?: string;
+    constructor(message: string, field?: string);
+}
+
+/**
+ * Main Synter SDK client.
+ *
+ * Transport per SPEC.md: nearly every tool dispatches through
+ * `POST /api/v1/tools/run` on `https://syntermedia.ai` with
+ * `{ script_name, args, platform? }`, auth via `Authorization: Bearer <key>`.
+ * Two tools bypass that dispatcher (`list_landing_pages`, `stage_audience_artifact`)
+ * — see `resources/audiences.ts` and `listLandingPages` below.
+ */
+
+/** Real, production base URL — see SPEC.md's "Transport" section. */
+declare const DEFAULT_BASE_URL = "https://syntermedia.ai";
+interface SynterConfig {
+    /** `syn_` + 32 base64url characters, issued at syntermedia.ai/developer. */
+    apiKey: string;
+    /** Override the base URL (defaults to `https://syntermedia.ai`). Mostly for tests. */
+    baseUrl?: string;
+    /** Request timeout in ms. Default 30000 (30s), per SPEC.md. */
+    timeout?: number;
+    /** Max retry attempts for 429s and network/timeout errors. Default 3, per SPEC.md. */
+    maxRetries?: number;
+    /** Inject a custom `fetch` implementation — primarily for testing without a real network. */
+    fetch?: typeof fetch;
+}
+interface UploadImageInput {
+    /** Source image URL. */
+    image_url: string;
+    /** Asset name for organization. */
+    asset_name: string;
+    /**
+     * Optional platform hint (google/meta/linkedin).
+     *
+     * KNOWN ISSUE (see SPEC.md "Known issues" #2, catalog.json `knownIssues`):
+     * live dispatch hardcodes `platform=google` unconditionally regardless of
+     * this value. Preserved verbatim — not silently "fixed" here.
+     */
+    platform?: 'google' | 'meta' | 'linkedin';
+}
+declare class Synter {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    readonly campaigns: CampaignsResource;
+    readonly analytics: AnalyticsResource;
+    readonly keywords: KeywordsResource;
+    readonly conversions: ConversionsResource;
+    readonly creative: CreativeResource;
+    readonly meta: MetaResource;
+    readonly linkedin: LinkedInResource;
+    readonly reddit: RedditResource;
+    readonly audiences: AudiencesResource;
+    /** AI-powered advertising toolbox for Amp integration — unchanged, out of scope for the transport rewrite. */
+    readonly amp: AmpToolbox;
+    constructor(config: SynterConfig | string, ampConfig?: AmpToolboxConfig);
+    /**
+     * Low-level dispatcher used by every typed resource method. Not usually
+     * called directly by SDK consumers — use `execute()` for the public
+     * escape hatch, or a typed resource method for everything else.
+     */
+    runTool(scriptName: string, args?: string[], platform?: string): Promise<Record<string, unknown>>;
+    /**
+     * Universal escape hatch mirroring the `run_tool` catalog tool: run any
+     * of the 140+ backend scripts by name. `args` is an idiomatic flag-name
+     * map (not a raw CLI string array) — converted internally the same way
+     * every other typed method builds its wire args.
+     */
+    execute(scriptName: string, args?: Record<string, string | number | boolean>, platform?: string): Promise<Record<string, unknown>>;
+    /** List all connected ad accounts across platforms. */
+    listAdAccounts(): Promise<Record<string, unknown>>;
+    /**
+     * Upload an image as an asset for use in ads.
+     *
+     * KNOWN ISSUE (SPEC.md "Known issues" #2): live dispatch hardcodes
+     * `platform=google` regardless of `input.platform`. Preserved verbatim.
+     */
+    uploadImage(input: UploadImageInput): Promise<Record<string, unknown>>;
+    /**
+     * List all landing pages for the authenticated workspace.
+     *
+     * Bypasses the primary `tools/run` dispatcher — special endpoint per
+     * SPEC.md/catalog.json `transport.special`: `GET /api/v1/landing-pages`.
+     */
+    listLandingPages(): Promise<Record<string, unknown>>;
+    private authHeaders;
+    /** The raw API key, for the small number of tools that need a non-Bearer header (e.g. `stage_audience_artifact`). */
+    getApiKey(): string;
+    /**
+     * Low-level generic HTTP helper retained for `AmpToolbox` and any other
+     * advanced/internal callers that need to hit an arbitrary path relative
+     * to the configured base URL, with the same retry/timeout/error
+     * semantics as the primary dispatcher.
+     */
+    request<T = unknown>(method: string, path: string, options?: {
+        body?: unknown;
+        query?: Record<string, unknown>;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    /**
+     * Sends a request to an arbitrary absolute URL with arbitrary headers —
+     * used by the two special-endpoint tools (`list_landing_pages` uses
+     * `request`/`runTool` against the default base URL; `stage_audience_artifact`
+     * needs a different host and a different auth header entirely).
+     */
+    sendAbsolute<T = unknown>(url: string, init: {
+        method: string;
+        headers: Record<string, string>;
+        body?: string;
+    }): Promise<T>;
+    /**
+     * Core transport: timeout + retry policy from SPEC.md — up to 3 retries,
+     * exponential backoff (1s base, 10s cap), retrying only 429 (honoring
+     * `Retry-After`) and network/timeout errors. Never retries other 4xx
+     * (or 5xx — not listed in SPEC.md's `retryOn`).
+     */
+    private sendWithRetry;
+    private toSynterError;
+}
+
+/**
+ * Legacy support types.
+ *
+ * These are unrelated to the catalog.json-driven tool methods (see
+ * `resources/*.ts` and `resources/shared-types.ts` for those) — they back
+ * `utils/utm.ts`, `utils/conversion-tracking.ts`, and
+ * `utils/analytics-integrations.ts`, which are out of scope for the
+ * transport rewrite and kept as-is. Trimmed of the fictional REST-API
+ * business types (`Campaign`, `Conversion`, `Agent*`, `DataExport*`, etc.)
+ * that used to live here alongside the old, non-functional client.
+ */
+type Platform = 'google' | 'reddit' | 'x';
+type PlatformStatus = 'connected' | 'disconnected' | 'error';
+interface PlatformConnection {
+    platform: Platform;
+    status: PlatformStatus;
+    accountId?: string;
+    accountName?: string;
+    connectedAt?: string;
+    lastSyncedAt?: string;
+}
+interface UTMTemplate {
+    source: string;
+    medium: string;
+    campaign: string;
+    content?: string;
+    term?: string;
+}
+interface UTMParameters extends UTMTemplate {
+    /** Auto-populated fields using platform macros */
+    dynamicFields?: Record<string, string>;
+}
+type AnalyticsPlatform = 'posthog' | 'heap' | 'mixpanel' | 'segment';
+interface AnalyticsEvent {
+    event: string;
+    properties?: Record<string, any>;
+    timestamp?: string;
+    userId?: string;
+    anonymousId?: string;
+}
+interface AnalyticsIntegrationConfig {
+    platform: AnalyticsPlatform;
+    apiKey: string;
+    enabled: boolean;
+}
+
+/**
+ * UTM parameter management utilities
+ *
+ * Handles automatic UTM generation with platform-specific macros
+ */
+
+/**
+ * Build complete UTM parameters with platform-specific macros
+ */
+declare function buildUTMParameters(template: UTMTemplate, platform: Platform): UTMParameters;
+/**
+ * Generate tracking URL with UTM parameters
+ */
+declare function buildTrackingURL(baseUrl: string, utmParams: UTMParameters): string;
+/**
+ * Extract UTM parameters from URL
+ */
+declare function extractUTMParameters(url: string): Partial<UTMParameters>;
+/**
+ * Validate UTM template
+ */
+declare function validateUTMTemplate(template: UTMTemplate): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Generate default UTM template for a campaign
+ */
+declare function generateDefaultUTMTemplate(platform: Platform, campaignName: string): UTMTemplate;
+
+/**
+ * Conversion tracking utilities
+ *
+ * Handles click ID detection and conversion event normalization
+ */
+
+/**
+ * Detect platform and click ID from URL parameters
+ */
+declare function detectClickId(urlOrParams: string | Record<string, string>): {
+    platform: Platform | null;
+    clickId: string | null;
+    paramName: string | null;
+};
+/**
+ * Extract all tracking parameters from URL
+ */
+interface TrackingParams {
+    clickIds: Partial<Record<Platform, string>>;
+    utm: {
+        source?: string;
+        medium?: string;
+        campaign?: string;
+        content?: string;
+        term?: string;
+    };
+    referrer?: string;
+}
+declare function extractTrackingParams(url: string, referrer?: string): TrackingParams;
+/**
+ * Validate click ID format by platform
+ */
+declare function validateClickId(platform: Platform, clickId: string): boolean;
+/**
+ * Build conversion payload for platform-specific APIs
+ */
+interface ConversionPayload {
+    platform: Platform;
+    clickId: string;
+    conversionName: string;
+    conversionTime: string;
+    value?: number;
+    currency?: string;
+    orderId?: string;
+}
+declare function buildConversionPayload(params: {
+    platform: Platform;
+    clickId: string;
+    event: string;
+    value?: number;
+    currency?: string;
+    timestamp?: string;
+    orderId?: string;
+}): ConversionPayload;
+declare function normalizeEventName(eventName: string, platform: Platform): string;
+
+/**
+ * Analytics platform integrations (PostHog, Heap, Mixpanel)
+ *
+ * Fan out ad events to downstream analytics tools
+ */
+
+interface AnalyticsIntegration {
+    platform: AnalyticsPlatform;
+    apiKey: string;
+    enabled: boolean;
+}
+/**
+ * Analytics integration manager
+ */
+declare class AnalyticsIntegrationManager {
+    private adapters;
+    constructor(integrations: AnalyticsIntegration[]);
+    /**
+     * Track event across all enabled integrations
+     */
+    track(event: AnalyticsEvent): Promise<void>;
+    /**
+     * Track event to specific platform
+     */
+    trackTo(platform: AnalyticsPlatform, event: AnalyticsEvent): Promise<void>;
+    /**
+     * Identify user across all enabled integrations
+     */
+    identify(userId: string, traits?: Record<string, any>): Promise<void>;
+}
+/**
+ * Normalize ad click event for analytics platforms
+ */
+declare function normalizeAdClickEvent(trackingParams: any): AnalyticsEvent;
+/**
+ * Normalize conversion event for analytics platforms
+ */
+declare function normalizeConversionEvent(params: {
+    event: string;
+    value?: number;
+    currency?: string;
+    platform?: string;
+    campaignId?: string;
+    metadata?: Record<string, any>;
+}): AnalyticsEvent;
+
+export { type AdPlatform, type AddKeywordsInput, type AddNegativeKeywordsInput, AmpToolbox, type AmpToolboxConfig, type AnalyticsEvent, type AnalyticsIntegration, type AnalyticsIntegrationConfig, AnalyticsIntegrationManager, type AnalyticsPlatform, AnalyticsResource, AudiencesResource, type CampaignBriefInput, CampaignsResource, type ConversionPayload, ConversionsResource, type CreateConversionInput, type CreateDisplayCampaignInput, type CreateLinkedInCampaignInput, type CreateMetaCampaignInput, type CreatePmaxCampaignInput, type CreateRedditCampaignInput, type CreateSearchCampaignInput, CreativeResource, type CreativeVariant, DEFAULT_BASE_URL, type DateRange, type DiagnoseTrackingInput, type GenerateImageInput, type GenerateVideoInput, type GeneratedCampaign, type GetDailySpendInput, type GetPerformanceInput, KeywordsResource, LinkedInResource, type ListCampaignsInput, type ManageAudienceInput, MetaResource, type OptimizationRecommendation, type PauseCampaignInput, type Platform, type PlatformConnection, type PlatformStatus, RedditResource, type StageAudienceArtifactInput, type StageAudienceArtifactResult, type SyncAudienceInput, Synter, type SynterConfig, SynterError, SynterValidationError, type TrackingParams, type UTMParameters, type UTMTemplate, type UpdateCampaignBudgetInput, type UploadImageInput, buildConversionPayload, buildTrackingURL, buildUTMParameters, Synter as default, detectClickId, extractTrackingParams, extractUTMParameters, generateDefaultUTMTemplate, normalizeAdClickEvent, normalizeConversionEvent, normalizeEventName, validateClickId, validateUTMTemplate };