@synterai/sdk-js 0.1.1 → 0.2.0

package/dist/index.mjs

@@ -98,7 +98,7 @@ function flattenArgsToFlags(args) {
 
 // src/resources/campaigns.ts
 var LIST_CAMPAIGNS_SCRIPT_BY_PLATFORM = {
-  google: "google_ads_list_campaigns",
+  google: "google_ads_get_campaigns",
   meta: "meta_ads_list_campaigns",
   linkedin: "linkedin_ads_list_campaigns",
   microsoft: "microsoft_ads_list_campaigns",
@@ -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,13 +222,79 @@ 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
 var GET_PERFORMANCE_SCRIPT_BY_PLATFORM = {
-  google: "pull_google_ads_data",
+  google: "pull_google_ads",
   meta: "pull_meta_ads",
-  linkedin: "pull_linkedin_ads_data",
+  linkedin: "pull_linkedin_ads",
   microsoft: "pull_microsoft_ads",
   reddit: "pull_reddit_ads",
   tiktok: "pull_tiktok_ads",
@@ -260,17 +326,22 @@ var AnalyticsResource = class {
       "google",
       input.platform
     );
-    const args = buildArgsFromMapping(GET_PERFORMANCE_ARG_MAPPING, input, platform);
+    const args = buildArgsFromMapping(
+      GET_PERFORMANCE_ARG_MAPPING,
+      { ...input, date_range: input.date_range ?? "LAST_7_DAYS" },
+      platform
+    );
     return this.client.runTool(scriptName, args, platform);
   }
   /** Get daily spend breakdown across all connected ad accounts. */
   async getDailySpend(input = {}) {
-    const platform = input.platform ?? "google";
-    const args = ["--platform", platform.toUpperCase()];
-    if (input.days !== void 0) {
-      args.push("--days", String(input.days));
-    }
-    return this.client.runTool("get_account_daily_spend", args, platform);
+    const { platform, scriptName } = resolvePlatformScriptName(
+      GET_PERFORMANCE_SCRIPT_BY_PLATFORM,
+      "google",
+      input.platform
+    );
+    const days = input.days ?? 7;
+    return this.client.runTool(scriptName, ["--days", String(days)], platform);
   }
 };
 
@@ -310,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;
@@ -335,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);
   }
 };
 
@@ -428,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",
@@ -460,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`.
    */
@@ -475,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(),
@@ -550,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 = {}) {
@@ -783,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;
@@ -801,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);
@@ -814,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);
   }
   // ---------------------------------------------------------------------
@@ -853,7 +1042,7 @@ var Synter = class {
   // ---------------------------------------------------------------------
   /** List all connected ad accounts across platforms. */
   async listAdAccounts() {
-    return this.runTool("google_ads_list_customers", [], "google");
+    return this.runTool("google_ads_get_customers", [], "google");
   }
   /**
    * Upload an image as an asset for use in ads.
@@ -892,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;
   }
@@ -1380,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.1",
-  "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",