@synterai/sdk-js 0.1.1 → 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

@@ -1,12 +1,12 @@
 # @synterai/sdk-js
 
-TypeScript SDK for the [Synter](https://syntermedia.ai) advertising API — manage campaigns across Google Ads, Meta, LinkedIn, Microsoft Ads, Reddit, TikTok, and X from your own code, with full types and IDE autocomplete.
+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.0` — early release.** Live on npm and installable, but pre-1.0: the surface may change before a stable `1.0`. Pin a version in production.
+> **`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
 
-Every method in this SDK calls the same live, production endpoint that powers Synter's MCP server (`@synterai/mcp-server`) and the `synter` CLI: `POST https://syntermedia.ai/api/v1/tools/run`. There is no separate "SDK backend" — if a method works here, it works because the exact same call already works for every MCP client (Claude, Cursor, Codex, ChatGPT) today.
+Every method in this SDK calls the same live, production endpoint that powers Synter's MCP server (`@synterai/mcp-server`) and the `synter` CLI: `POST https://syntermedia.ai/api/v1/tools/run`. There is no separate "SDK backend" — if a method works here, it works because the exact same call already works for every MCP client (Claude, Cursor, Codex, Devin, ChatGPT) today.
 
 See [`../sdk-shared/SPEC.md`](../sdk-shared/SPEC.md) and [`../sdk-shared/catalog.json`](../sdk-shared/catalog.json) for the full transport contract this SDK — and every sibling-language SDK — implements.
 
@@ -18,7 +18,7 @@ npm install @synterai/sdk-js
 
 ## Authentication
 
-Get an API key at [syntermedia.ai/developer](https://syntermedia.ai/developer). Keys look like `syn_` followed by 32 base64url characters.
+Get an API key at [syntermedia.ai/developer](https://syntermedia.ai/developer). Keys look like `syn_` followed by 32 base64url characters. Keys issued from a sandbox workspace use the `syn_test_` prefix instead and only work against that sandbox — no live ad-account risk.
 
 > **⚠️ Server-side only.** Your `SYNTER_API_KEY` is a secret that can spend money and modify your ad accounts. Use this SDK from a **backend** — a Node service, a Next.js API route or Server Action, an edge/serverless function. **Never** instantiate `Synter` in client-side code (React components, browser bundles, mobile apps); the key would ship to every visitor. For a React/SPA frontend, call your own backend, and have the backend call Synter.
 
@@ -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>;
+    }>;
 }
 
 /**
@@ -161,9 +189,7 @@ declare class CampaignsResource {
  * 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.
+ * uses the same platform-routed pull scripts with `--days` (default 7).
  */
 
 interface GetPerformanceInput {
@@ -219,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 {
@@ -234,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);
@@ -252,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>>;
 }
 
 /**
@@ -421,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`.
      */
@@ -444,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
  *
@@ -963,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. */
@@ -1000,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;
@@ -1012,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);
@@ -1045,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
@@ -1257,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 };