@synterai/sdk-js 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.2.0 — 2026-10-02
+
+Metadata: public repo link (Synter-Media-AI/synter-docs), synterai.com homepage, hello@synterai.com author, and the official-packages provenance line in the README.
+
+Default production URLs and documentation links now use synterai.com. The artifact API uses api.synterai.com where applicable.
+
+Explicit `baseUrl` and `artifactBaseUrl` options take precedence over `SYNTER_API_URL` and `SYNTER_ARTIFACT_API_URL` in Node.js. Browser clients can use the options without a `process` global.
+
+The syntermedia.ai machine endpoints remain dual-served for previously published versions and explicit overrides.

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript SDK for the [Synter](https://syntermedia.ai) advertising API — manage campaigns across 27 ad platforms (Google Ads, Meta, LinkedIn, Microsoft, Reddit, TikTok, X, Amazon DSP, Amazon Ads, Pinterest, Snap, Spotify, OpenAI Ads, The Trade Desk, FreeWheel, DV360, CM360, Walmart Connect, Instacart Ads, Target Roundel, Criteo) from your own code, with full types and IDE autocomplete.
 
-> **`0.1.2` — live on npm.** Pre-1.0: the surface may change before a stable `1.0`. Pin a version in production. `0.1.2` fixes `analytics.getPerformance({ platform: "google" | "linkedin" })`, which in `0.1.0`/`0.1.1` sent the script *filename* (`pull_google_ads_data`) instead of the canonical script name (`pull_google_ads`); the backend rejected it with `400 UNKNOWN_TOOL` until it gained an alias on 2026-08-27.
+> **`0.1.2` — live on npm.** Pre-1.0: the surface may change before a stable `1.0`. Pin a version in production. `0.1.2` fixes `analytics.getPerformance({ platform: "google" | "linkedin" })`, which in `0.1.0`/`0.1.1` sent the script *filename* (`pull_google_ads_data`) instead of the canonical script name (`pull_google_ads`); the backend rejected it with `400 UNKNOWN_TOOL` until it gained an alias on 2026-08-27 (synter-media PR #9684).
 
 ## What this actually talks to
 
@@ -64,6 +64,68 @@ const image = await synter.creative.generateImage({ prompt: 'a running shoe on a
 await synter.execute('google_ads_list_audiences', { status: 'ENABLED' }, 'google');
 ```
 
+## Post-Write Readback Verification (Agent Safety Pattern)
+
+When coding agents or automated scripts modify campaign state (such as pausing overspending campaigns or halving daily budgets), **never trust an HTTP 200 `{success: true}` alone**. Always execute an explicit post-write readback to verify that the upstream ad platform actually persisted and confirmed the state change:
+
+```ts
+import { Synter } from '@synterai/sdk-js';
+
+const synter = new Synter(process.env.SYNTER_API_KEY!);
+
+async function optimizeCampaignBudget(campaignId: string, targetCpa: number, isDryRun = true) {
+  // 1. Fetch 7-day performance
+  const perf = await synter.analytics.getPerformance({ platform: 'google', date_range: 'LAST_7_DAYS' });
+  const campaign = (perf.campaigns as any[])?.find(c => c.id === campaignId || c.campaign_id === campaignId);
+
+  if (!campaign) throw new Error(`Campaign ${campaignId} not found`);
+
+  const cost = Number(campaign.cost || 0);
+  const conversions = Number(campaign.conversions || 0);
+
+  // Handle missing or zero conversions explicitly — never guess a CPA
+  if (conversions <= 0) {
+    console.log(`[SKIP] Campaign ${campaignId}: 0 conversions recorded, CPA is undefined.`);
+    return;
+  }
+
+  const cpa = cost / conversions;
+  if (cpa <= targetCpa) {
+    console.log(`[OK] Campaign ${campaignId}: CPA $${cpa.toFixed(2)} <= threshold $${targetCpa}. No action needed.`);
+    return;
+  }
+
+  const currentBudget = Number(campaign.daily_budget || campaign.budget || 50);
+  const newBudget = Math.max(1, Math.round(currentBudget * 0.5));
+
+  console.log(`[ACTION] Campaign ${campaignId}: CPA $${cpa.toFixed(2)} > threshold $${targetCpa}. Target: PAUSE and cut budget to $${newBudget}/day.`);
+
+  if (isDryRun) {
+    console.log(`[DRY RUN] Would pause campaign ${campaignId} and reduce daily budget from $${currentBudget} to $${newBudget}.`);
+    return;
+  }
+
+  // 2. Execute mutations in apply mode
+  const pauseResult = await synter.campaigns.pause({ campaign_id: campaignId, platform: 'google' });
+  const budgetResult = await synter.campaigns.updateBudget({ campaign_id: campaignId, platform: 'google', daily_budget: newBudget });
+
+  // 3. MANDATORY POST-WRITE READBACK VERIFICATION
+  // Re-read campaign state from Google Ads to verify provider applied the mutations
+  const refreshed = await synter.campaigns.list({ platform: 'google' });
+  const verified = (refreshed.campaigns as any[])?.find(c => c.id === campaignId || c.campaign_id === campaignId);
+
+  if (!verified) {
+    throw new Error(`Readback verification failed: Campaign ${campaignId} not returned in refreshed list.`);
+  }
+
+  if (verified.status !== 'PAUSED') {
+    throw new Error(`Readback verification failed: Campaign ${campaignId} status is '${verified.status}', expected 'PAUSED'.`);
+  }
+
+  console.log(`[VERIFIED] Campaign ${campaignId} successfully paused and daily budget reduced to $${newBudget}. Confirmed on live platform.`);
+}
+```
+
 ## API surface
 
 Methods are grouped by category, matching the tool catalog:

package/dist/index.d.mts

@@ -153,6 +153,34 @@ declare class CampaignsResource {
      * dispatches with `platform=google` regardless of input.
      */
     updateBudget(input: UpdateCampaignBudgetInput): Promise<Record<string, unknown>>;
+    /**
+     * Update campaign budget with deterministic readback verification.
+     *
+     * Executes the budget update, waits for propagation, and reads back
+     * campaign status from the platform to verify the update succeeded on the wire.
+     */
+    updateBudgetAndVerify(input: UpdateCampaignBudgetInput & {
+        maxWaitMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<{
+        mutation: Record<string, unknown>;
+        verified: boolean;
+        readback?: Record<string, unknown>;
+    }>;
+    /**
+     * Pause a campaign with deterministic readback verification.
+     *
+     * Executes the pause command, waits for propagation, and reads back
+     * campaign status from the platform to verify status === 'PAUSED' on the wire.
+     */
+    pauseAndVerify(input: PauseCampaignInput & {
+        maxWaitMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<{
+        mutation: Record<string, unknown>;
+        verified: boolean;
+        readback?: Record<string, unknown>;
+    }>;
 }
 
 /**
@@ -217,7 +245,8 @@ declare class KeywordsResource {
 
 /**
  * `conversions` category — catalog.json tools: create_conversion,
- * list_conversions, diagnose_tracking.
+ * list_conversions, diagnose_tracking, get_pixel_health,
+ * list_event_deliveries, get_click_attribution.
  */
 
 interface CreateConversionInput {
@@ -232,6 +261,21 @@ interface DiagnoseTrackingInput {
     /** Website URL to check. */
     url: string;
 }
+interface GetPixelHealthInput {
+    site_key?: string;
+}
+interface ListEventDeliveriesInput {
+    site_key?: string;
+    status?: 'PENDING' | 'SUCCESS' | 'RETRYING' | 'FAILED';
+    platform?: string;
+    limit?: number;
+}
+interface GetClickAttributionInput {
+    site_key?: string;
+    user_id?: number;
+    email?: string;
+    limit?: number;
+}
 declare class ConversionsResource {
     private readonly client;
     constructor(client: Synter);
@@ -250,6 +294,9 @@ declare class ConversionsResource {
      * credentials (SPEC.md's "Platform resolution" rule 3).
      */
     diagnoseTracking(input: DiagnoseTrackingInput): Promise<Record<string, unknown>>;
+    getPixelHealth(input?: GetPixelHealthInput): Promise<Record<string, unknown>>;
+    listEventDeliveries(input?: ListEventDeliveriesInput): Promise<Record<string, unknown>>;
+    getClickAttribution(input?: GetClickAttributionInput): Promise<Record<string, unknown>>;
 }
 
 /**
@@ -419,7 +466,7 @@ declare class AudiencesResource {
      * identifiers inline when over ~500 entries.
      *
      * Bypasses the primary `tools/run` dispatcher: different host
-     * (`https://api.syntermedia.ai`) and a different auth header
+     * (`https://api.synterai.com`) and a different auth header
      * (`X-Synter-Key`, not `Authorization: Bearer`) — see SPEC.md/catalog.json
      * `transport.special`.
      */
@@ -442,6 +489,127 @@ declare class AudiencesResource {
     manage(input: ManageAudienceInput): Promise<Record<string, unknown>>;
 }
 
+/**
+ * `shield` category — Agent Shield spend limits, burst thresholds,
+ * circuit breakers, and kill-switch inspection.
+ */
+
+interface InspectShieldInput {
+    platform?: AdPlatform;
+}
+interface AgentShieldPolicy {
+    policy_id: string;
+    name: string;
+    enforced: boolean;
+    max_daily_spend_usd: number;
+    max_hourly_spend_usd: number;
+    burst_threshold_multiplier: number;
+    circuit_breaker_active: boolean;
+    kill_switch_engaged: boolean;
+}
+declare class ShieldResource {
+    private readonly client;
+    constructor(client: Synter);
+    /**
+     * Inspect Agent Shield velocity limits, burst thresholds, circuit breakers,
+     * and kill-switch status before executing ad-spend mutations.
+     */
+    inspect(input?: InspectShieldInput): Promise<{
+        status: 'ACTIVE' | 'TRIPPED' | 'PAUSED';
+        policies: AgentShieldPolicy[];
+        kill_switch_engaged: boolean;
+        notice: string;
+    }>;
+}
+
+/**
+ * `angstrom` category — Synter Ångström attribution claim verification.
+ */
+
+interface VerifyAngstromClaimInput {
+    platform?: AdPlatform;
+    claimed_conversions?: number;
+    claimed_revenue_usd?: number;
+    touchpoint_ids?: string[];
+}
+interface AngstromVerificationResult {
+    confidence_score: number;
+    verdict: 'VERIFIED' | 'DISPUTED' | 'UNVERIFIABLE';
+    incremental_lift_multiplier: number;
+    deterministic_touchpoints_verified: number;
+    rubric: {
+        single_touch_discount: number;
+        cross_network_dedup_factor: number;
+        latency_decay_score: number;
+    };
+    explanation: string;
+}
+declare class AngstromResource {
+    private readonly client;
+    constructor(client: Synter);
+    /**
+     * Verify attribution claims against Synter Ångström's deterministic confidence rubric.
+     */
+    verify(input?: VerifyAngstromClaimInput): Promise<AngstromVerificationResult>;
+}
+
+/**
+ * `skills` category — Core autonomous growth playbooks.
+ */
+
+type GrowthSkillId = 'pmax-brand-cannibalization' | 'search-hygiene-shield' | 'marginal-cpa-budget-rebalancer' | 'meta-asc-dark-pool-auditor' | 'single-truth-attribution';
+interface GrowthSkillPlaybook {
+    skill_id: GrowthSkillId;
+    name: string;
+    category: string;
+    description: string;
+    required_tools: string[];
+    execution_steps: string[];
+    safety_checks: string[];
+    expected_outcome: string;
+}
+declare class SkillsResource {
+    private readonly client;
+    constructor(client: Synter);
+    /**
+     * Load an autonomous growth runbook by ID.
+     */
+    get(skillId: GrowthSkillId): Promise<GrowthSkillPlaybook>;
+    /**
+     * List available autonomous growth runbook IDs.
+     */
+    list(): GrowthSkillId[];
+}
+
+/**
+ * `visibility` category — LLM search brand visibility and AEO share of voice.
+ */
+
+interface GetVisibilityInput {
+    query?: string;
+    competitor_domains?: string[];
+}
+interface EngineVisibilityScore {
+    engine: 'chatgpt' | 'claude' | 'perplexity' | 'gemini';
+    share_of_voice_pct: number;
+    mention_count: number;
+    ranking_position_avg: number;
+}
+interface VisibilityReportResult {
+    brand: string;
+    overall_aeo_score: number;
+    engines: EngineVisibilityScore[];
+    recommendations: string[];
+}
+declare class VisibilityResource {
+    private readonly client;
+    constructor(client: Synter);
+    /**
+     * Read AI search brand visibility and AEO share of voice across ChatGPT, Claude, Perplexity, and Gemini.
+     */
+    get(input?: GetVisibilityInput): Promise<VisibilityReportResult>;
+}
+
 /**
  * Amp Custom Advertising Toolbox
  *
@@ -961,19 +1129,22 @@ declare class SynterValidationError extends Error {
  * Main Synter SDK client.
  *
  * Transport per SPEC.md: nearly every tool dispatches through
- * `POST /api/v1/tools/run` on `https://syntermedia.ai` with
+ * `POST /api/v1/tools/run` on `https://synterai.com` 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";
+declare const DEFAULT_BASE_URL = "https://synterai.com";
+declare const DEFAULT_ARTIFACT_BASE_URL = "https://api.synterai.com";
 interface SynterConfig {
-    /** `syn_` + 32 base64url characters, issued at syntermedia.ai/developer. */
+    /** `syn_` + 32 base64url characters, issued at synterai.com/developer. */
     apiKey: string;
-    /** Override the base URL (defaults to `https://syntermedia.ai`). Mostly for tests. */
+    /** Primary API URL. Takes precedence over SYNTER_API_URL in Node.js. */
     baseUrl?: string;
+    /** Artifact API URL. Takes precedence over SYNTER_ARTIFACT_API_URL in Node.js. */
+    artifactBaseUrl?: 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. */
@@ -998,6 +1169,7 @@ interface UploadImageInput {
 declare class Synter {
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly artifactBaseUrl;
     private readonly timeout;
     private readonly maxRetries;
     private readonly fetchImpl;
@@ -1010,6 +1182,10 @@ declare class Synter {
     readonly linkedin: LinkedInResource;
     readonly reddit: RedditResource;
     readonly audiences: AudiencesResource;
+    readonly shield: ShieldResource;
+    readonly angstrom: AngstromResource;
+    readonly skills: SkillsResource;
+    readonly visibility: VisibilityResource;
     /** AI-powered advertising toolbox for Amp integration — unchanged, out of scope for the transport rewrite. */
     readonly amp: AmpToolbox;
     constructor(config: SynterConfig | string, ampConfig?: AmpToolboxConfig);
@@ -1043,7 +1219,9 @@ declare class Synter {
      */
     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`). */
+    /** Artifact host used by audience staging. */
+    getArtifactBaseUrl(): string;
+    /** The raw API key, for tools that need a non-Bearer header. */
     getApiKey(): string;
     /**
      * Low-level generic HTTP helper retained for `AmpToolbox` and any other
@@ -1255,4 +1433,4 @@ declare function normalizeConversionEvent(params: {
     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 };
+export { type AdPlatform, type AddKeywordsInput, type AddNegativeKeywordsInput, type AgentShieldPolicy, AmpToolbox, type AmpToolboxConfig, type AnalyticsEvent, type AnalyticsIntegration, type AnalyticsIntegrationConfig, AnalyticsIntegrationManager, type AnalyticsPlatform, AnalyticsResource, AngstromResource, type AngstromVerificationResult, 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_ARTIFACT_BASE_URL, DEFAULT_BASE_URL, type DateRange, type DiagnoseTrackingInput, type EngineVisibilityScore, type GenerateImageInput, type GenerateVideoInput, type GeneratedCampaign, type GetDailySpendInput, type GetPerformanceInput, type GetVisibilityInput, type GrowthSkillId, type GrowthSkillPlaybook, type InspectShieldInput, KeywordsResource, LinkedInResource, type ListCampaignsInput, type ManageAudienceInput, MetaResource, type OptimizationRecommendation, type PauseCampaignInput, type Platform, type PlatformConnection, type PlatformStatus, RedditResource, ShieldResource, SkillsResource, type StageAudienceArtifactInput, type StageAudienceArtifactResult, type SyncAudienceInput, Synter, type SynterConfig, SynterError, SynterValidationError, type TrackingParams, type UTMParameters, type UTMTemplate, type UpdateCampaignBudgetInput, type UploadImageInput, type VerifyAngstromClaimInput, type VisibilityReportResult, VisibilityResource, buildConversionPayload, buildTrackingURL, buildUTMParameters, Synter as default, detectClickId, extractTrackingParams, extractUTMParameters, generateDefaultUTMTemplate, normalizeAdClickEvent, normalizeConversionEvent, normalizeEventName, validateClickId, validateUTMTemplate };

package/dist/index.d.ts

@@ -153,6 +153,34 @@ declare class CampaignsResource {
      * dispatches with `platform=google` regardless of input.
      */
     updateBudget(input: UpdateCampaignBudgetInput): Promise<Record<string, unknown>>;
+    /**
+     * Update campaign budget with deterministic readback verification.
+     *
+     * Executes the budget update, waits for propagation, and reads back
+     * campaign status from the platform to verify the update succeeded on the wire.
+     */
+    updateBudgetAndVerify(input: UpdateCampaignBudgetInput & {
+        maxWaitMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<{
+        mutation: Record<string, unknown>;
+        verified: boolean;
+        readback?: Record<string, unknown>;
+    }>;
+    /**
+     * Pause a campaign with deterministic readback verification.
+     *
+     * Executes the pause command, waits for propagation, and reads back
+     * campaign status from the platform to verify status === 'PAUSED' on the wire.
+     */
+    pauseAndVerify(input: PauseCampaignInput & {
+        maxWaitMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<{
+        mutation: Record<string, unknown>;
+        verified: boolean;
+        readback?: Record<string, unknown>;
+    }>;
 }
 
 /**
@@ -217,7 +245,8 @@ declare class KeywordsResource {
 
 /**
  * `conversions` category — catalog.json tools: create_conversion,
- * list_conversions, diagnose_tracking.
+ * list_conversions, diagnose_tracking, get_pixel_health,
+ * list_event_deliveries, get_click_attribution.
  */
 
 interface CreateConversionInput {
@@ -232,6 +261,21 @@ interface DiagnoseTrackingInput {
     /** Website URL to check. */
     url: string;
 }
+interface GetPixelHealthInput {
+    site_key?: string;
+}
+interface ListEventDeliveriesInput {
+    site_key?: string;
+    status?: 'PENDING' | 'SUCCESS' | 'RETRYING' | 'FAILED';
+    platform?: string;
+    limit?: number;
+}
+interface GetClickAttributionInput {
+    site_key?: string;
+    user_id?: number;
+    email?: string;
+    limit?: number;
+}
 declare class ConversionsResource {
     private readonly client;
     constructor(client: Synter);
@@ -250,6 +294,9 @@ declare class ConversionsResource {
      * credentials (SPEC.md's "Platform resolution" rule 3).
      */
     diagnoseTracking(input: DiagnoseTrackingInput): Promise<Record<string, unknown>>;
+    getPixelHealth(input?: GetPixelHealthInput): Promise<Record<string, unknown>>;
+    listEventDeliveries(input?: ListEventDeliveriesInput): Promise<Record<string, unknown>>;
+    getClickAttribution(input?: GetClickAttributionInput): Promise<Record<string, unknown>>;
 }
 
 /**
@@ -419,7 +466,7 @@ declare class AudiencesResource {
      * identifiers inline when over ~500 entries.
      *
      * Bypasses the primary `tools/run` dispatcher: different host
-     * (`https://api.syntermedia.ai`) and a different auth header
+     * (`https://api.synterai.com`) and a different auth header
      * (`X-Synter-Key`, not `Authorization: Bearer`) — see SPEC.md/catalog.json
      * `transport.special`.
      */
@@ -442,6 +489,127 @@ declare class AudiencesResource {
     manage(input: ManageAudienceInput): Promise<Record<string, unknown>>;
 }
 
+/**
+ * `shield` category — Agent Shield spend limits, burst thresholds,
+ * circuit breakers, and kill-switch inspection.
+ */
+
+interface InspectShieldInput {
+    platform?: AdPlatform;
+}
+interface AgentShieldPolicy {
+    policy_id: string;
+    name: string;
+    enforced: boolean;
+    max_daily_spend_usd: number;
+    max_hourly_spend_usd: number;
+    burst_threshold_multiplier: number;
+    circuit_breaker_active: boolean;
+    kill_switch_engaged: boolean;
+}
+declare class ShieldResource {
+    private readonly client;
+    constructor(client: Synter);
+    /**
+     * Inspect Agent Shield velocity limits, burst thresholds, circuit breakers,
+     * and kill-switch status before executing ad-spend mutations.
+     */
+    inspect(input?: InspectShieldInput): Promise<{
+        status: 'ACTIVE' | 'TRIPPED' | 'PAUSED';
+        policies: AgentShieldPolicy[];
+        kill_switch_engaged: boolean;
+        notice: string;
+    }>;
+}
+
+/**
+ * `angstrom` category — Synter Ångström attribution claim verification.
+ */
+
+interface VerifyAngstromClaimInput {
+    platform?: AdPlatform;
+    claimed_conversions?: number;
+    claimed_revenue_usd?: number;
+    touchpoint_ids?: string[];
+}
+interface AngstromVerificationResult {
+    confidence_score: number;
+    verdict: 'VERIFIED' | 'DISPUTED' | 'UNVERIFIABLE';
+    incremental_lift_multiplier: number;
+    deterministic_touchpoints_verified: number;
+    rubric: {
+        single_touch_discount: number;
+        cross_network_dedup_factor: number;
+        latency_decay_score: number;
+    };
+    explanation: string;
+}
+declare class AngstromResource {
+    private readonly client;
+    constructor(client: Synter);
+    /**
+     * Verify attribution claims against Synter Ångström's deterministic confidence rubric.
+     */
+    verify(input?: VerifyAngstromClaimInput): Promise<AngstromVerificationResult>;
+}
+
+/**
+ * `skills` category — Core autonomous growth playbooks.
+ */
+
+type GrowthSkillId = 'pmax-brand-cannibalization' | 'search-hygiene-shield' | 'marginal-cpa-budget-rebalancer' | 'meta-asc-dark-pool-auditor' | 'single-truth-attribution';
+interface GrowthSkillPlaybook {
+    skill_id: GrowthSkillId;
+    name: string;
+    category: string;
+    description: string;
+    required_tools: string[];
+    execution_steps: string[];
+    safety_checks: string[];
+    expected_outcome: string;
+}
+declare class SkillsResource {
+    private readonly client;
+    constructor(client: Synter);
+    /**
+     * Load an autonomous growth runbook by ID.
+     */
+    get(skillId: GrowthSkillId): Promise<GrowthSkillPlaybook>;
+    /**
+     * List available autonomous growth runbook IDs.
+     */
+    list(): GrowthSkillId[];
+}
+
+/**
+ * `visibility` category — LLM search brand visibility and AEO share of voice.
+ */
+
+interface GetVisibilityInput {
+    query?: string;
+    competitor_domains?: string[];
+}
+interface EngineVisibilityScore {
+    engine: 'chatgpt' | 'claude' | 'perplexity' | 'gemini';
+    share_of_voice_pct: number;
+    mention_count: number;
+    ranking_position_avg: number;
+}
+interface VisibilityReportResult {
+    brand: string;
+    overall_aeo_score: number;
+    engines: EngineVisibilityScore[];
+    recommendations: string[];
+}
+declare class VisibilityResource {
+    private readonly client;
+    constructor(client: Synter);
+    /**
+     * Read AI search brand visibility and AEO share of voice across ChatGPT, Claude, Perplexity, and Gemini.
+     */
+    get(input?: GetVisibilityInput): Promise<VisibilityReportResult>;
+}
+
 /**
  * Amp Custom Advertising Toolbox
  *
@@ -961,19 +1129,22 @@ declare class SynterValidationError extends Error {
  * Main Synter SDK client.
  *
  * Transport per SPEC.md: nearly every tool dispatches through
- * `POST /api/v1/tools/run` on `https://syntermedia.ai` with
+ * `POST /api/v1/tools/run` on `https://synterai.com` 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";
+declare const DEFAULT_BASE_URL = "https://synterai.com";
+declare const DEFAULT_ARTIFACT_BASE_URL = "https://api.synterai.com";
 interface SynterConfig {
-    /** `syn_` + 32 base64url characters, issued at syntermedia.ai/developer. */
+    /** `syn_` + 32 base64url characters, issued at synterai.com/developer. */
     apiKey: string;
-    /** Override the base URL (defaults to `https://syntermedia.ai`). Mostly for tests. */
+    /** Primary API URL. Takes precedence over SYNTER_API_URL in Node.js. */
     baseUrl?: string;
+    /** Artifact API URL. Takes precedence over SYNTER_ARTIFACT_API_URL in Node.js. */
+    artifactBaseUrl?: 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. */
@@ -998,6 +1169,7 @@ interface UploadImageInput {
 declare class Synter {
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly artifactBaseUrl;
     private readonly timeout;
     private readonly maxRetries;
     private readonly fetchImpl;
@@ -1010,6 +1182,10 @@ declare class Synter {
     readonly linkedin: LinkedInResource;
     readonly reddit: RedditResource;
     readonly audiences: AudiencesResource;
+    readonly shield: ShieldResource;
+    readonly angstrom: AngstromResource;
+    readonly skills: SkillsResource;
+    readonly visibility: VisibilityResource;
     /** AI-powered advertising toolbox for Amp integration — unchanged, out of scope for the transport rewrite. */
     readonly amp: AmpToolbox;
     constructor(config: SynterConfig | string, ampConfig?: AmpToolboxConfig);
@@ -1043,7 +1219,9 @@ declare class Synter {
      */
     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`). */
+    /** Artifact host used by audience staging. */
+    getArtifactBaseUrl(): string;
+    /** The raw API key, for tools that need a non-Bearer header. */
     getApiKey(): string;
     /**
      * Low-level generic HTTP helper retained for `AmpToolbox` and any other
@@ -1255,4 +1433,4 @@ declare function normalizeConversionEvent(params: {
     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 };
+export { type AdPlatform, type AddKeywordsInput, type AddNegativeKeywordsInput, type AgentShieldPolicy, AmpToolbox, type AmpToolboxConfig, type AnalyticsEvent, type AnalyticsIntegration, type AnalyticsIntegrationConfig, AnalyticsIntegrationManager, type AnalyticsPlatform, AnalyticsResource, AngstromResource, type AngstromVerificationResult, 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_ARTIFACT_BASE_URL, DEFAULT_BASE_URL, type DateRange, type DiagnoseTrackingInput, type EngineVisibilityScore, type GenerateImageInput, type GenerateVideoInput, type GeneratedCampaign, type GetDailySpendInput, type GetPerformanceInput, type GetVisibilityInput, type GrowthSkillId, type GrowthSkillPlaybook, type InspectShieldInput, KeywordsResource, LinkedInResource, type ListCampaignsInput, type ManageAudienceInput, MetaResource, type OptimizationRecommendation, type PauseCampaignInput, type Platform, type PlatformConnection, type PlatformStatus, RedditResource, ShieldResource, SkillsResource, type StageAudienceArtifactInput, type StageAudienceArtifactResult, type SyncAudienceInput, Synter, type SynterConfig, SynterError, SynterValidationError, type TrackingParams, type UTMParameters, type UTMTemplate, type UpdateCampaignBudgetInput, type UploadImageInput, type VerifyAngstromClaimInput, type VisibilityReportResult, VisibilityResource, buildConversionPayload, buildTrackingURL, buildUTMParameters, Synter as default, detectClickId, extractTrackingParams, extractUTMParameters, generateDefaultUTMTemplate, normalizeAdClickEvent, normalizeConversionEvent, normalizeEventName, validateClickId, validateUTMTemplate };

package/dist/index.js

@@ -23,18 +23,23 @@ __export(index_exports, {
   AmpToolbox: () => AmpToolbox,
   AnalyticsIntegrationManager: () => AnalyticsIntegrationManager,
   AnalyticsResource: () => AnalyticsResource,
+  AngstromResource: () => AngstromResource,
   AudiencesResource: () => AudiencesResource,
   CampaignsResource: () => CampaignsResource,
   ConversionsResource: () => ConversionsResource,
   CreativeResource: () => CreativeResource,
+  DEFAULT_ARTIFACT_BASE_URL: () => DEFAULT_ARTIFACT_BASE_URL,
   DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
   KeywordsResource: () => KeywordsResource,
   LinkedInResource: () => LinkedInResource,
   MetaResource: () => MetaResource,
   RedditResource: () => RedditResource,
+  ShieldResource: () => ShieldResource,
+  SkillsResource: () => SkillsResource,
   Synter: () => Synter,
   SynterError: () => SynterError,
   SynterValidationError: () => SynterValidationError,
+  VisibilityResource: () => VisibilityResource,
   buildConversionPayload: () => buildConversionPayload,
   buildTrackingURL: () => buildTrackingURL,
   buildUTMParameters: () => buildUTMParameters,
@@ -202,7 +207,7 @@ var PAUSE_CAMPAIGN_ARG_MAPPING = [
 ];
 var UPDATE_BUDGET_ARG_MAPPING = [
   { field: "campaign_id", flag: "--campaign-id", type: "string", required: true },
-  { field: "daily_budget", flag: "--budget", type: "number", required: true }
+  { field: "daily_budget", flag: "--daily-budget", type: "number", required: true }
 ];
 var CampaignsResource = class {
   constructor(client) {
@@ -275,6 +280,72 @@ var CampaignsResource = class {
     const args = buildArgsFromMapping(UPDATE_BUDGET_ARG_MAPPING, input);
     return this.client.runTool("update_campaign_budget", args, "google");
   }
+  /**
+   * Update campaign budget with deterministic readback verification.
+   *
+   * Executes the budget update, waits for propagation, and reads back
+   * campaign status from the platform to verify the update succeeded on the wire.
+   */
+  async updateBudgetAndVerify(input) {
+    const mutation = await this.updateBudget(input);
+    const maxWaitMs = input.maxWaitMs ?? 5e3;
+    const pollIntervalMs = input.pollIntervalMs ?? 1e3;
+    const startTime = Date.now();
+    let lastReadback;
+    while (Date.now() - startTime <= maxWaitMs) {
+      try {
+        const readback = await this.list({
+          platform: input.platform
+        });
+        lastReadback = readback;
+        const campaigns = readback.campaigns || readback.data || [];
+        const match = campaigns.find(
+          (c) => String(c.id || c.campaign_id) === String(input.campaign_id)
+        );
+        if (match) {
+          const budget = Number(match.daily_budget_usd || match.daily_budget || match.budget);
+          if (Math.abs(budget - input.daily_budget) < 0.01) {
+            return { mutation, verified: true, readback: match };
+          }
+        }
+      } catch {
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    return { mutation, verified: false, readback: lastReadback };
+  }
+  /**
+   * Pause a campaign with deterministic readback verification.
+   *
+   * Executes the pause command, waits for propagation, and reads back
+   * campaign status from the platform to verify status === 'PAUSED' on the wire.
+   */
+  async pauseAndVerify(input) {
+    const mutation = await this.pause(input);
+    const maxWaitMs = input.maxWaitMs ?? 5e3;
+    const pollIntervalMs = input.pollIntervalMs ?? 1e3;
+    const startTime = Date.now();
+    let lastReadback;
+    while (Date.now() - startTime <= maxWaitMs) {
+      try {
+        const readback = await this.list({
+          platform: input.platform,
+          status: "PAUSED"
+        });
+        lastReadback = readback;
+        const campaigns = readback.campaigns || readback.data || [];
+        const match = campaigns.find(
+          (c) => String(c.id || c.campaign_id) === String(input.campaign_id)
+        );
+        if (match) {
+          return { mutation, verified: true, readback: match };
+        }
+      } catch {
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    return { mutation, verified: false, readback: lastReadback };
+  }
 };
 
 // src/resources/analytics.ts
@@ -368,6 +439,21 @@ var CREATE_CONVERSION_ARG_MAPPING = [
 var DIAGNOSE_TRACKING_ARG_MAPPING = [
   { field: "url", flag: "--url", type: "string", required: true }
 ];
+var GET_PIXEL_HEALTH_ARG_MAPPING = [
+  { field: "site_key", flag: "--site-key", type: "string" }
+];
+var LIST_EVENT_DELIVERIES_ARG_MAPPING = [
+  { field: "site_key", flag: "--site-key", type: "string" },
+  { field: "status", flag: "--status", type: "string" },
+  { field: "platform", flag: "--platform", type: "string" },
+  { field: "limit", flag: "--limit", type: "number" }
+];
+var GET_CLICK_ATTRIBUTION_ARG_MAPPING = [
+  { field: "site_key", flag: "--site-key", type: "string" },
+  { field: "user_id", flag: "--user-id", type: "number" },
+  { field: "email", flag: "--email", type: "string" },
+  { field: "limit", flag: "--limit", type: "number" }
+];
 var ConversionsResource = class {
   constructor(client) {
     this.client = client;
@@ -393,7 +479,19 @@ var ConversionsResource = class {
    */
   async diagnoseTracking(input) {
     const args = buildArgsFromMapping(DIAGNOSE_TRACKING_ARG_MAPPING, input);
-    return this.client.runTool("diagnose_conversion_tracking", args);
+    return this.client.runTool("diagnose_tracking", args);
+  }
+  async getPixelHealth(input = {}) {
+    const args = buildArgsFromMapping(GET_PIXEL_HEALTH_ARG_MAPPING, input);
+    return this.client.runTool("get_pixel_health", args);
+  }
+  async listEventDeliveries(input = {}) {
+    const args = buildArgsFromMapping(LIST_EVENT_DELIVERIES_ARG_MAPPING, input);
+    return this.client.runTool("list_event_deliveries", args);
+  }
+  async getClickAttribution(input = {}) {
+    const args = buildArgsFromMapping(GET_CLICK_ATTRIBUTION_ARG_MAPPING, input);
+    return this.client.runTool("get_click_attribution", args);
   }
 };
 
@@ -486,7 +584,6 @@ var RedditResource = class {
 
 // src/resources/audiences.ts
 var CONSENT_WARNING = "[@synterai/sdk-js] i_have_consent was not provided. Confirm lawful basis under GDPR/CCPA and the destination platform's terms for every identifier before staging or syncing PII, then pass `i_have_consent: true`. (Soft-launch notice \u2014 mirrors the backend's own behavior; this call is not blocked.)";
-var ARTIFACT_ENDPOINT = "https://api.syntermedia.ai/artifacts/audience-sync-input";
 var SYNC_AUDIENCE_SCRIPT_BY_PLATFORM = {
   google: "google_ads_create_customer_match",
   meta: "meta_ads_create_audience",
@@ -518,7 +615,7 @@ var AudiencesResource = class {
    * identifiers inline when over ~500 entries.
    *
    * Bypasses the primary `tools/run` dispatcher: different host
-   * (`https://api.syntermedia.ai`) and a different auth header
+   * (`https://api.synterai.com`) and a different auth header
    * (`X-Synter-Key`, not `Authorization: Bearer`) — see SPEC.md/catalog.json
    * `transport.special`.
    */
@@ -533,7 +630,7 @@ var AudiencesResource = class {
     if (input.script_name !== void 0) payload.script_name = input.script_name;
     if (input.ttl_seconds !== void 0) payload.ttl_seconds = input.ttl_seconds;
     if (input.i_have_consent !== void 0) payload.i_have_consent = input.i_have_consent;
-    return this.client.sendAbsolute(ARTIFACT_ENDPOINT, {
+    return this.client.sendAbsolute(`${this.client.getArtifactBaseUrl()}/artifacts/audience-sync-input`, {
       method: "POST",
       headers: {
         "X-Synter-Key": this.client.getApiKey(),
@@ -608,6 +705,91 @@ var AudiencesResource = class {
   }
 };
 
+// src/resources/shield.ts
+var ShieldResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Inspect Agent Shield velocity limits, burst thresholds, circuit breakers,
+   * and kill-switch status before executing ad-spend mutations.
+   */
+  async inspect(input = {}) {
+    const args = [];
+    if (input.platform) {
+      args.push("--platform", input.platform);
+    }
+    const result = await this.client.runTool("inspect_agent_shield", args, input.platform);
+    return result;
+  }
+};
+
+// src/resources/angstrom.ts
+var AngstromResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Verify attribution claims against Synter Ångström's deterministic confidence rubric.
+   */
+  async verify(input = {}) {
+    const args = [];
+    if (input.platform) args.push("--platform", input.platform);
+    if (input.claimed_conversions !== void 0) args.push("--conversions", String(input.claimed_conversions));
+    if (input.claimed_revenue_usd !== void 0) args.push("--revenue", String(input.claimed_revenue_usd));
+    if (input.touchpoint_ids && input.touchpoint_ids.length > 0) {
+      args.push("--touchpoints", input.touchpoint_ids.join(","));
+    }
+    const result = await this.client.runTool("verify_angstrom_claim", args, input.platform);
+    return result;
+  }
+};
+
+// src/resources/skills.ts
+var SkillsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Load an autonomous growth runbook by ID.
+   */
+  async get(skillId) {
+    const result = await this.client.runTool("get_skill", ["--skill-id", skillId]);
+    return result;
+  }
+  /**
+   * List available autonomous growth runbook IDs.
+   */
+  list() {
+    return [
+      "pmax-brand-cannibalization",
+      "search-hygiene-shield",
+      "marginal-cpa-budget-rebalancer",
+      "meta-asc-dark-pool-auditor",
+      "single-truth-attribution"
+    ];
+  }
+};
+
+// src/resources/visibility.ts
+var VisibilityResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Read AI search brand visibility and AEO share of voice across ChatGPT, Claude, Perplexity, and Gemini.
+   */
+  async get(input = {}) {
+    const args = [];
+    if (input.query) args.push("--query", input.query);
+    if (input.competitor_domains && input.competitor_domains.length > 0) {
+      args.push("--competitors", input.competitor_domains.join(","));
+    }
+    const result = await this.client.runTool("get_llm_visibility", args);
+    return result;
+  }
+};
+
 // src/toolbox/amp-tools.ts
 var AmpToolbox = class {
   constructor(client, config = {}) {
@@ -841,7 +1023,8 @@ var AmpToolbox = class {
 };
 
 // src/client.ts
-var DEFAULT_BASE_URL = "https://syntermedia.ai";
+var DEFAULT_BASE_URL = "https://synterai.com";
+var DEFAULT_ARTIFACT_BASE_URL = "https://api.synterai.com";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 3;
 var RETRY_BASE_MS = 1e3;
@@ -859,7 +1042,9 @@ var Synter = class {
       throw new SynterValidationError("`apiKey` is required to construct a Synter client.", "apiKey");
     }
     this.apiKey = fullConfig.apiKey;
-    this.baseUrl = fullConfig.baseUrl ?? DEFAULT_BASE_URL;
+    const env = typeof process !== "undefined" ? process.env : void 0;
+    this.baseUrl = fullConfig.baseUrl ?? (env?.SYNTER_API_URL || DEFAULT_BASE_URL);
+    this.artifactBaseUrl = fullConfig.artifactBaseUrl ?? (env?.SYNTER_ARTIFACT_API_URL || DEFAULT_ARTIFACT_BASE_URL);
     this.timeout = fullConfig.timeout ?? DEFAULT_TIMEOUT_MS;
     this.maxRetries = fullConfig.maxRetries ?? DEFAULT_MAX_RETRIES;
     this.fetchImpl = fullConfig.fetch ?? globalThis.fetch.bind(globalThis);
@@ -872,6 +1057,10 @@ var Synter = class {
     this.linkedin = new LinkedInResource(this);
     this.reddit = new RedditResource(this);
     this.audiences = new AudiencesResource(this);
+    this.shield = new ShieldResource(this);
+    this.angstrom = new AngstromResource(this);
+    this.skills = new SkillsResource(this);
+    this.visibility = new VisibilityResource(this);
     this.amp = new AmpToolbox(this, ampConfig);
   }
   // ---------------------------------------------------------------------
@@ -950,7 +1139,11 @@ var Synter = class {
       "Content-Type": "application/json"
     };
   }
-  /** The raw API key, for the small number of tools that need a non-Bearer header (e.g. `stage_audience_artifact`). */
+  /** Artifact host used by audience staging. */
+  getArtifactBaseUrl() {
+    return this.artifactBaseUrl;
+  }
+  /** The raw API key, for tools that need a non-Bearer header. */
   getApiKey() {
     return this.apiKey;
   }
@@ -1439,18 +1632,23 @@ function normalizeConversionEvent(params) {
   AmpToolbox,
   AnalyticsIntegrationManager,
   AnalyticsResource,
+  AngstromResource,
   AudiencesResource,
   CampaignsResource,
   ConversionsResource,
   CreativeResource,
+  DEFAULT_ARTIFACT_BASE_URL,
   DEFAULT_BASE_URL,
   KeywordsResource,
   LinkedInResource,
   MetaResource,
   RedditResource,
+  ShieldResource,
+  SkillsResource,
   Synter,
   SynterError,
   SynterValidationError,
+  VisibilityResource,
   buildConversionPayload,
   buildTrackingURL,
   buildUTMParameters,

package/dist/index.mjs

@@ -149,7 +149,7 @@ var PAUSE_CAMPAIGN_ARG_MAPPING = [
 ];
 var UPDATE_BUDGET_ARG_MAPPING = [
   { field: "campaign_id", flag: "--campaign-id", type: "string", required: true },
-  { field: "daily_budget", flag: "--budget", type: "number", required: true }
+  { field: "daily_budget", flag: "--daily-budget", type: "number", required: true }
 ];
 var CampaignsResource = class {
   constructor(client) {
@@ -222,6 +222,72 @@ var CampaignsResource = class {
     const args = buildArgsFromMapping(UPDATE_BUDGET_ARG_MAPPING, input);
     return this.client.runTool("update_campaign_budget", args, "google");
   }
+  /**
+   * Update campaign budget with deterministic readback verification.
+   *
+   * Executes the budget update, waits for propagation, and reads back
+   * campaign status from the platform to verify the update succeeded on the wire.
+   */
+  async updateBudgetAndVerify(input) {
+    const mutation = await this.updateBudget(input);
+    const maxWaitMs = input.maxWaitMs ?? 5e3;
+    const pollIntervalMs = input.pollIntervalMs ?? 1e3;
+    const startTime = Date.now();
+    let lastReadback;
+    while (Date.now() - startTime <= maxWaitMs) {
+      try {
+        const readback = await this.list({
+          platform: input.platform
+        });
+        lastReadback = readback;
+        const campaigns = readback.campaigns || readback.data || [];
+        const match = campaigns.find(
+          (c) => String(c.id || c.campaign_id) === String(input.campaign_id)
+        );
+        if (match) {
+          const budget = Number(match.daily_budget_usd || match.daily_budget || match.budget);
+          if (Math.abs(budget - input.daily_budget) < 0.01) {
+            return { mutation, verified: true, readback: match };
+          }
+        }
+      } catch {
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    return { mutation, verified: false, readback: lastReadback };
+  }
+  /**
+   * Pause a campaign with deterministic readback verification.
+   *
+   * Executes the pause command, waits for propagation, and reads back
+   * campaign status from the platform to verify status === 'PAUSED' on the wire.
+   */
+  async pauseAndVerify(input) {
+    const mutation = await this.pause(input);
+    const maxWaitMs = input.maxWaitMs ?? 5e3;
+    const pollIntervalMs = input.pollIntervalMs ?? 1e3;
+    const startTime = Date.now();
+    let lastReadback;
+    while (Date.now() - startTime <= maxWaitMs) {
+      try {
+        const readback = await this.list({
+          platform: input.platform,
+          status: "PAUSED"
+        });
+        lastReadback = readback;
+        const campaigns = readback.campaigns || readback.data || [];
+        const match = campaigns.find(
+          (c) => String(c.id || c.campaign_id) === String(input.campaign_id)
+        );
+        if (match) {
+          return { mutation, verified: true, readback: match };
+        }
+      } catch {
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    return { mutation, verified: false, readback: lastReadback };
+  }
 };
 
 // src/resources/analytics.ts
@@ -315,6 +381,21 @@ var CREATE_CONVERSION_ARG_MAPPING = [
 var DIAGNOSE_TRACKING_ARG_MAPPING = [
   { field: "url", flag: "--url", type: "string", required: true }
 ];
+var GET_PIXEL_HEALTH_ARG_MAPPING = [
+  { field: "site_key", flag: "--site-key", type: "string" }
+];
+var LIST_EVENT_DELIVERIES_ARG_MAPPING = [
+  { field: "site_key", flag: "--site-key", type: "string" },
+  { field: "status", flag: "--status", type: "string" },
+  { field: "platform", flag: "--platform", type: "string" },
+  { field: "limit", flag: "--limit", type: "number" }
+];
+var GET_CLICK_ATTRIBUTION_ARG_MAPPING = [
+  { field: "site_key", flag: "--site-key", type: "string" },
+  { field: "user_id", flag: "--user-id", type: "number" },
+  { field: "email", flag: "--email", type: "string" },
+  { field: "limit", flag: "--limit", type: "number" }
+];
 var ConversionsResource = class {
   constructor(client) {
     this.client = client;
@@ -340,7 +421,19 @@ var ConversionsResource = class {
    */
   async diagnoseTracking(input) {
     const args = buildArgsFromMapping(DIAGNOSE_TRACKING_ARG_MAPPING, input);
-    return this.client.runTool("diagnose_conversion_tracking", args);
+    return this.client.runTool("diagnose_tracking", args);
+  }
+  async getPixelHealth(input = {}) {
+    const args = buildArgsFromMapping(GET_PIXEL_HEALTH_ARG_MAPPING, input);
+    return this.client.runTool("get_pixel_health", args);
+  }
+  async listEventDeliveries(input = {}) {
+    const args = buildArgsFromMapping(LIST_EVENT_DELIVERIES_ARG_MAPPING, input);
+    return this.client.runTool("list_event_deliveries", args);
+  }
+  async getClickAttribution(input = {}) {
+    const args = buildArgsFromMapping(GET_CLICK_ATTRIBUTION_ARG_MAPPING, input);
+    return this.client.runTool("get_click_attribution", args);
   }
 };
 
@@ -433,7 +526,6 @@ var RedditResource = class {
 
 // src/resources/audiences.ts
 var CONSENT_WARNING = "[@synterai/sdk-js] i_have_consent was not provided. Confirm lawful basis under GDPR/CCPA and the destination platform's terms for every identifier before staging or syncing PII, then pass `i_have_consent: true`. (Soft-launch notice \u2014 mirrors the backend's own behavior; this call is not blocked.)";
-var ARTIFACT_ENDPOINT = "https://api.syntermedia.ai/artifacts/audience-sync-input";
 var SYNC_AUDIENCE_SCRIPT_BY_PLATFORM = {
   google: "google_ads_create_customer_match",
   meta: "meta_ads_create_audience",
@@ -465,7 +557,7 @@ var AudiencesResource = class {
    * identifiers inline when over ~500 entries.
    *
    * Bypasses the primary `tools/run` dispatcher: different host
-   * (`https://api.syntermedia.ai`) and a different auth header
+   * (`https://api.synterai.com`) and a different auth header
    * (`X-Synter-Key`, not `Authorization: Bearer`) — see SPEC.md/catalog.json
    * `transport.special`.
    */
@@ -480,7 +572,7 @@ var AudiencesResource = class {
     if (input.script_name !== void 0) payload.script_name = input.script_name;
     if (input.ttl_seconds !== void 0) payload.ttl_seconds = input.ttl_seconds;
     if (input.i_have_consent !== void 0) payload.i_have_consent = input.i_have_consent;
-    return this.client.sendAbsolute(ARTIFACT_ENDPOINT, {
+    return this.client.sendAbsolute(`${this.client.getArtifactBaseUrl()}/artifacts/audience-sync-input`, {
       method: "POST",
       headers: {
         "X-Synter-Key": this.client.getApiKey(),
@@ -555,6 +647,91 @@ var AudiencesResource = class {
   }
 };
 
+// src/resources/shield.ts
+var ShieldResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Inspect Agent Shield velocity limits, burst thresholds, circuit breakers,
+   * and kill-switch status before executing ad-spend mutations.
+   */
+  async inspect(input = {}) {
+    const args = [];
+    if (input.platform) {
+      args.push("--platform", input.platform);
+    }
+    const result = await this.client.runTool("inspect_agent_shield", args, input.platform);
+    return result;
+  }
+};
+
+// src/resources/angstrom.ts
+var AngstromResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Verify attribution claims against Synter Ångström's deterministic confidence rubric.
+   */
+  async verify(input = {}) {
+    const args = [];
+    if (input.platform) args.push("--platform", input.platform);
+    if (input.claimed_conversions !== void 0) args.push("--conversions", String(input.claimed_conversions));
+    if (input.claimed_revenue_usd !== void 0) args.push("--revenue", String(input.claimed_revenue_usd));
+    if (input.touchpoint_ids && input.touchpoint_ids.length > 0) {
+      args.push("--touchpoints", input.touchpoint_ids.join(","));
+    }
+    const result = await this.client.runTool("verify_angstrom_claim", args, input.platform);
+    return result;
+  }
+};
+
+// src/resources/skills.ts
+var SkillsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Load an autonomous growth runbook by ID.
+   */
+  async get(skillId) {
+    const result = await this.client.runTool("get_skill", ["--skill-id", skillId]);
+    return result;
+  }
+  /**
+   * List available autonomous growth runbook IDs.
+   */
+  list() {
+    return [
+      "pmax-brand-cannibalization",
+      "search-hygiene-shield",
+      "marginal-cpa-budget-rebalancer",
+      "meta-asc-dark-pool-auditor",
+      "single-truth-attribution"
+    ];
+  }
+};
+
+// src/resources/visibility.ts
+var VisibilityResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Read AI search brand visibility and AEO share of voice across ChatGPT, Claude, Perplexity, and Gemini.
+   */
+  async get(input = {}) {
+    const args = [];
+    if (input.query) args.push("--query", input.query);
+    if (input.competitor_domains && input.competitor_domains.length > 0) {
+      args.push("--competitors", input.competitor_domains.join(","));
+    }
+    const result = await this.client.runTool("get_llm_visibility", args);
+    return result;
+  }
+};
+
 // src/toolbox/amp-tools.ts
 var AmpToolbox = class {
   constructor(client, config = {}) {
@@ -788,7 +965,8 @@ var AmpToolbox = class {
 };
 
 // src/client.ts
-var DEFAULT_BASE_URL = "https://syntermedia.ai";
+var DEFAULT_BASE_URL = "https://synterai.com";
+var DEFAULT_ARTIFACT_BASE_URL = "https://api.synterai.com";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 3;
 var RETRY_BASE_MS = 1e3;
@@ -806,7 +984,9 @@ var Synter = class {
       throw new SynterValidationError("`apiKey` is required to construct a Synter client.", "apiKey");
     }
     this.apiKey = fullConfig.apiKey;
-    this.baseUrl = fullConfig.baseUrl ?? DEFAULT_BASE_URL;
+    const env = typeof process !== "undefined" ? process.env : void 0;
+    this.baseUrl = fullConfig.baseUrl ?? (env?.SYNTER_API_URL || DEFAULT_BASE_URL);
+    this.artifactBaseUrl = fullConfig.artifactBaseUrl ?? (env?.SYNTER_ARTIFACT_API_URL || DEFAULT_ARTIFACT_BASE_URL);
     this.timeout = fullConfig.timeout ?? DEFAULT_TIMEOUT_MS;
     this.maxRetries = fullConfig.maxRetries ?? DEFAULT_MAX_RETRIES;
     this.fetchImpl = fullConfig.fetch ?? globalThis.fetch.bind(globalThis);
@@ -819,6 +999,10 @@ var Synter = class {
     this.linkedin = new LinkedInResource(this);
     this.reddit = new RedditResource(this);
     this.audiences = new AudiencesResource(this);
+    this.shield = new ShieldResource(this);
+    this.angstrom = new AngstromResource(this);
+    this.skills = new SkillsResource(this);
+    this.visibility = new VisibilityResource(this);
     this.amp = new AmpToolbox(this, ampConfig);
   }
   // ---------------------------------------------------------------------
@@ -897,7 +1081,11 @@ var Synter = class {
       "Content-Type": "application/json"
     };
   }
-  /** The raw API key, for the small number of tools that need a non-Bearer header (e.g. `stage_audience_artifact`). */
+  /** Artifact host used by audience staging. */
+  getArtifactBaseUrl() {
+    return this.artifactBaseUrl;
+  }
+  /** The raw API key, for tools that need a non-Bearer header. */
   getApiKey() {
     return this.apiKey;
   }
@@ -1385,18 +1573,23 @@ export {
   AmpToolbox,
   AnalyticsIntegrationManager,
   AnalyticsResource,
+  AngstromResource,
   AudiencesResource,
   CampaignsResource,
   ConversionsResource,
   CreativeResource,
+  DEFAULT_ARTIFACT_BASE_URL,
   DEFAULT_BASE_URL,
   KeywordsResource,
   LinkedInResource,
   MetaResource,
   RedditResource,
+  ShieldResource,
+  SkillsResource,
   Synter,
   SynterError,
   SynterValidationError,
+  VisibilityResource,
   buildConversionPayload,
   buildTrackingURL,
   buildUTMParameters,

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@synterai/sdk-js",
-  "version": "0.1.2",
-  "description": "TypeScript SDK for the Synter advertising API — manage campaigns across Google Ads, Meta, LinkedIn, Reddit, Microsoft, TikTok, and X",
+  "version": "0.2.0",
+  "description": "Official Synter TypeScript SDK for the Synter advertising API — manage campaigns across Google Ads, Meta, LinkedIn, Reddit, Microsoft, TikTok, and X. @iflow-mcp/* copies are unofficial.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
@@ -42,15 +43,15 @@
     "analytics",
     "ppc"
   ],
-  "author": "SynterMedia",
+  "author": "Synter <hello@synterai.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jshorwitz/synter-media.git",
-    "directory": "packages/sdk-js"
+    "url": "git+https://github.com/Synter-Media-AI/synter-docs.git",
+    "directory": "sdk/typescript"
   },
-  "homepage": "https://syntermedia.ai",
-  "bugs": "https://github.com/jshorwitz/synter-media/issues",
+  "homepage": "https://synterai.com",
+  "bugs": "https://github.com/Synter-Media-AI/synter-docs/issues",
   "dependencies": {},
   "devDependencies": {
     "@types/node": "^20.10.0",