From 344ed752dd87266944eb4e04e8966dfb269208e4 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Mon, 13 Jul 2026 17:48:55 -0400
Subject: [PATCH] feat(media-use): tag HeyGen calls with X-HeyGen-Client-Source
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Send `X-HeyGen-Client-Source: media-use` on every media-use HeyGen API
request (both auth types, via heygenAuthHeaders + the heygenJSON transport),
so backend billing meta can isolate media-use consumption from other free
TTS and avatar-video usage. Unconditional of auth type — a paying user's
media-use call is still media-use — unlike the OAuth-only cli-source header
that gates the free allowance.
---
 skills-manifest.json                               |  2 +-
 skills/media-use/audio/scripts/lib/heygen.mjs      | 11 +++++++++--
 skills/media-use/audio/scripts/lib/heygen.test.mjs |  9 ++++++---
 3 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/skills-manifest.json b/skills-manifest.json
index eff6fea255..e6780a95e5 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -46,7 +46,7 @@
       "files": 10
     },
     "media-use": {
-      "hash": "688ce2db33d293bc",
+      "hash": "ea061d942d97f2c2",
       "files": 124
     },
     "motion-graphics": {
diff --git a/skills/media-use/audio/scripts/lib/heygen.mjs b/skills/media-use/audio/scripts/lib/heygen.mjs
index e74614ec7b..ed784ffd40 100644
--- a/skills/media-use/audio/scripts/lib/heygen.mjs
+++ b/skills/media-use/audio/scripts/lib/heygen.mjs
@@ -10,6 +10,11 @@ import { dirname, join, resolve } from "node:path";
 
 export const HEYGEN_BASE = "https://api.heygen.com/v3";
 export const HEYGEN_CLI_SOURCE_HEADERS = { "X-HeyGen-Source": "cli" };
+// Tool-attribution sent on EVERY media-use HeyGen call regardless of auth type, so
+// the backend can isolate media-use consumption from other free TTS / avatar video.
+// Unconditional — a paying user's media-use call is still media-use — unlike the
+// OAuth-only cli-source header above, which also gates the free allowance.
+export const HEYGEN_CLIENT_SOURCE_HEADERS = { "X-HeyGen-Client-Source": "media-use" };
 
 // Walk up ≤5 dirs from startDir; load the first .env (shell env always wins).
 export function loadEnvFromDir(startDir) {
@@ -88,7 +93,9 @@ export function heygenAuthHeaders() {
     // grant the free allowance for OAuth requests and ignores it for API-key
     // (X-Api-Key) traffic, where it's dead metadata.
     const isOauth = "Authorization" in cred.headers;
-    return isOauth ? { ...cred.headers, ...HEYGEN_CLI_SOURCE_HEADERS } : { ...cred.headers };
+    return isOauth
+      ? { ...cred.headers, ...HEYGEN_CLI_SOURCE_HEADERS, ...HEYGEN_CLIENT_SOURCE_HEADERS }
+      : { ...cred.headers, ...HEYGEN_CLIENT_SOURCE_HEADERS };
   }
   if (cred?.expired)
     throw new Error(
@@ -101,7 +108,7 @@ export function heygenAuthHeaders() {
 
 // Authed JSON request against the v3 API; throws on a non-OK status.
 export async function heygenJSON(path, { method = "GET", headers = {}, body } = {}) {
-  const opts = { method, headers: { ...headers } };
+  const opts = { method, headers: { ...HEYGEN_CLIENT_SOURCE_HEADERS, ...headers } };
   if (body !== undefined) {
     opts.headers["Content-Type"] = "application/json";
     opts.body = JSON.stringify(body);
diff --git a/skills/media-use/audio/scripts/lib/heygen.test.mjs b/skills/media-use/audio/scripts/lib/heygen.test.mjs
index 629a17fd15..22542f3552 100644
--- a/skills/media-use/audio/scripts/lib/heygen.test.mjs
+++ b/skills/media-use/audio/scripts/lib/heygen.test.mjs
@@ -24,18 +24,20 @@ function withCleanHeygenEnv(fn) {
   }
 }
 
-test("heygenAuthHeaders does not tag API-key requests as CLI traffic", () => {
+test("heygenAuthHeaders does not tag API-key requests as CLI traffic, but still carries the media-use tool tag", () => {
   withCleanHeygenEnv(() => {
     process.env.HEYGEN_API_KEY = "hg_test";
     // API-key requests use normal billing; the backend ignores the cli-source
-    // header for them, so it's not sent.
+    // header for them, so it's not sent. The tool-attribution header IS sent on
+    // every media-use call (any auth type) so the backend can isolate media-use.
     assert.deepEqual(heygenAuthHeaders(), {
       "X-Api-Key": "hg_test",
+      "X-HeyGen-Client-Source": "media-use",
     });
   });
 });
 
-test("heygenAuthHeaders tags OAuth requests as CLI traffic", () => {
+test("heygenAuthHeaders tags OAuth requests as CLI traffic and with the media-use tool tag", () => {
   withCleanHeygenEnv(() => {
     const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
     try {
@@ -52,6 +54,7 @@ test("heygenAuthHeaders tags OAuth requests as CLI traffic", () => {
       assert.deepEqual(heygenAuthHeaders(), {
         Authorization: "Bearer at_test",
         "X-HeyGen-Source": "cli",
+        "X-HeyGen-Client-Source": "media-use",
       });
     } finally {
       rmSync(dir, { recursive: true, force: true });