@nerdsnipe-inc/apple-ads-mcp-server 0.0.0-stage → 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,100 @@
+import { createAppleAdsApi, type AppleAdsApi } from "@apple/apple-ads-platform";
+import { type ServerConfig } from "./config.js";
+export declare const DEFAULT_BASE_URL = "https://api.ads.apple.com/v1";
+export declare const DEFAULT_AUTH_BASE_URL = "https://appleid.apple.com/";
+export interface RateLimitState {
+    limit?: number;
+    remaining?: number;
+    /** epoch ms when the current window resets */
+    resetAtMs?: number;
+    observedAtMs?: number;
+    last429?: {
+        atMs: number;
+        retryAfterMs?: number;
+    };
+}
+export interface ClientDeps {
+    /** Replace the SDK factory (tests). */
+    createApi?: typeof createAppleAdsApi;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    stderr?: (line: string) => void;
+}
+export interface InvokeOptions {
+    /** Safe to retry on 5xx / network failures (reads, PUT, DELETE). 429 is always retried. */
+    idempotent: boolean;
+}
+export interface AdAccountSummary {
+    id: string;
+    name?: string;
+    orgId?: string;
+}
+/** Normalise APPLE_ADS_BASE_URL: strip trailing slashes (SDK paths already start with "/"). */
+export declare function normalizeBaseUrl(url: string | undefined): string;
+/**
+ * APPLE_ADS_TOKEN_URL may be an auth base URL ("https://host/") or the full token URL
+ * (".../auth/oauth2/token"). The SDK wants the base with a trailing slash.
+ */
+export declare function normalizeAuthBaseUrl(url: string | undefined): string;
+/** Retry-After is either delta-seconds or an HTTP date. */
+export declare function parseRetryAfter(value: string | undefined, nowMs: number): number | undefined;
+export declare class AppleAdsClient {
+    readonly config: ServerConfig;
+    private apiPromise?;
+    private aclPromise?;
+    private mePromise?;
+    private readonly sleep;
+    private readonly now;
+    private readonly createApi;
+    private readonly stderr;
+    readonly rate: RateLimitState;
+    constructor(config: ServerConfig, deps?: ClientDeps);
+    /** Values that must never appear in output. */
+    secrets(): string[];
+    /** Lazily build (and memoise) the SDK client. A failed attempt is not cached. */
+    getApi(): Promise<AppleAdsApi>;
+    /** Drop the cached SDK client (forces a fresh token fetch on next use). */
+    resetApi(): void;
+    private log;
+    private buildApi;
+    /** Record RateLimit-* / Retry-After headers from any response. */
+    observe(headers: unknown, status: number): void;
+    private throttle;
+    private backoffMs;
+    /**
+     * Run `fn` with 429 / 5xx / network retries.
+     * - 401 is handled inside the SDK (token refresh + one retry).
+     * - 429 always retries, honouring Retry-After (then RateLimit-Reset, then capped exponential backoff).
+     * - 5xx and transient network errors retry only when `idempotent`.
+     */
+    withRetries<T>(fn: () => Promise<T>, opts: InvokeOptions): Promise<T>;
+    /** Call an SDK operation by its method name with positional SDK arguments. */
+    invoke(operationId: string, args: unknown[], opts: InvokeOptions): Promise<{
+        status: number;
+        data: unknown;
+    }>;
+    /** Raw authenticated request through the SDK's axios instance (auth + 401 refresh + error mapping included). */
+    raw(method: string, apiPath: string, o: {
+        query?: Record<string, unknown>;
+        body?: unknown;
+        context?: string;
+    }): Promise<{
+        status: number;
+        data: unknown;
+    }>;
+    /** "123" -> "adAccountId=123"; an explicit "adAccountId=123" / "orgId=..." string passes through. */
+    static formatContext(id: string | number): string;
+    /** Extract the numeric/string ad account id from a context header value. */
+    static adAccountIdFromContext(ctx: string | undefined): string | undefined;
+    /** Ad accounts the API user can access (GET /acls), cached for 5 minutes. */
+    listAdAccounts(): Promise<AdAccountSummary[]>;
+    /**
+     * Resolve the X-AP-Context header value.
+     * explicit arg -> APPLE_ADS_AD_ACCOUNT_ID -> (if `required`) the only accessible ad account
+     * (narrowed by APPLE_ADS_ORG_ID when set).
+     */
+    resolveContext(adAccountId: string | number | undefined, required: boolean): Promise<string | undefined>;
+    /** orgId argument -> APPLE_ADS_ORG_ID -> orgId from GET /me. */
+    resolveOrgId(orgId: string | number | undefined): Promise<string>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,iBAAiB,EAEjB,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAGpE,eAAO,MAAM,gBAAgB,iCAAiC,CAAC;AAC/D,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAGlE,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAED,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,SAAS,CAAC,EAAE,OAAO,iBAAiB,CAAC;IACrC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,2FAA2F;IAC3F,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD,+FAA+F;AAC/F,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEhE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKpE;AAUD,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO5F;AAED,qBAAa,cAAc;IAWvB,QAAQ,CAAC,MAAM,EAAE,YAAY;IAV/B,OAAO,CAAC,UAAU,CAAC,CAAuB;IAC1C,OAAO,CAAC,UAAU,CAAC,CAAiD;IACpE,OAAO,CAAC,SAAS,CAAC,CAA+C;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAM;gBAGxB,MAAM,EAAE,YAAY,EAC7B,IAAI,GAAE,UAAe;IAQvB,+CAA+C;IAC/C,OAAO,IAAI,MAAM,EAAE;IAMnB,iFAAiF;IACjF,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC;IAU9B,2EAA2E;IAC3E,QAAQ,IAAI,IAAI;IAIhB,OAAO,CAAC,GAAG;YAOG,QAAQ;IA6EtB,kEAAkE;IAClE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;YAgBjC,QAAQ;IAatB,OAAO,CAAC,SAAS;IAKjB;;;;;OAKG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC;IAiC3E,8EAA8E;IACxE,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IAWnH,gHAAgH;IAC1G,GAAG,CACP,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GACvE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IA0B7C,qGAAqG;IACrG,MAAM,CAAC,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAKjD,4EAA4E;IAC5E,MAAM,CAAC,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS;IAM1E,6EAA6E;IACvE,cAAc,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAqBnD;;;;OAIG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAqB9G,gEAAgE;IAC1D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;CAiBxE"}

package/dist/client.js

@@ -0,0 +1,352 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createAppleAdsApi, ApiRequestError, } from "@apple/apple-ads-platform";
+import { ConfigError, AppleAdsToolError } from "./errors.js";
+import { missingCredentials } from "./config.js";
+import { redact } from "./redact.js";
+export const DEFAULT_BASE_URL = "https://api.ads.apple.com/v1";
+export const DEFAULT_AUTH_BASE_URL = "https://appleid.apple.com/";
+const TOKEN_PATH = "auth/oauth2/token";
+const NETWORK_RETRY_CODES = new Set(["ECONNRESET", "ETIMEDOUT", "ECONNABORTED", "EAI_AGAIN", "EPIPE"]);
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Normalise APPLE_ADS_BASE_URL: strip trailing slashes (SDK paths already start with "/"). */
+export function normalizeBaseUrl(url) {
+    return (url ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+/**
+ * APPLE_ADS_TOKEN_URL may be an auth base URL ("https://host/") or the full token URL
+ * (".../auth/oauth2/token"). The SDK wants the base with a trailing slash.
+ */
+export function normalizeAuthBaseUrl(url) {
+    if (!url)
+        return DEFAULT_AUTH_BASE_URL;
+    let u = url.trim();
+    if (u.endsWith(TOKEN_PATH))
+        u = u.slice(0, -TOKEN_PATH.length);
+    return u.endsWith("/") ? u : u + "/";
+}
+function headerValue(headers, name) {
+    if (!headers)
+        return undefined;
+    const h = headers;
+    const v = typeof h.get === "function" ? h.get(name) : (h[name] ?? h[name.toLowerCase()]);
+    if (v === undefined || v === null)
+        return undefined;
+    return Array.isArray(v) ? String(v[0]) : String(v);
+}
+/** Retry-After is either delta-seconds or an HTTP date. */
+export function parseRetryAfter(value, nowMs) {
+    if (!value)
+        return undefined;
+    const secs = Number(value);
+    if (Number.isFinite(secs) && secs >= 0)
+        return Math.round(secs * 1000);
+    const date = Date.parse(value);
+    if (!Number.isNaN(date))
+        return Math.max(0, date - nowMs);
+    return undefined;
+}
+export class AppleAdsClient {
+    config;
+    apiPromise;
+    aclPromise;
+    mePromise;
+    sleep;
+    now;
+    createApi;
+    stderr;
+    rate = {};
+    constructor(config, deps = {}) {
+        this.config = config;
+        this.sleep = deps.sleep ?? defaultSleep;
+        this.now = deps.now ?? Date.now;
+        this.createApi = deps.createApi ?? createAppleAdsApi;
+        this.stderr = deps.stderr ?? ((l) => process.stderr.write(l + "\n"));
+    }
+    /** Values that must never appear in output. */
+    secrets() {
+        return [this.config.privateKey, this.config.clientId, this.config.keyId, this.config.teamId].filter(Boolean);
+    }
+    // ───────────────────────── authentication / SDK client ─────────────────────────
+    /** Lazily build (and memoise) the SDK client. A failed attempt is not cached. */
+    getApi() {
+        if (!this.apiPromise) {
+            this.apiPromise = this.buildApi().catch((e) => {
+                this.apiPromise = undefined;
+                throw e;
+            });
+        }
+        return this.apiPromise;
+    }
+    /** Drop the cached SDK client (forces a fresh token fetch on next use). */
+    resetApi() {
+        this.apiPromise = undefined;
+    }
+    log(level, message, meta) {
+        const order = ["debug", "info", "warn", "error", "silent"];
+        if (order.indexOf(level) < order.indexOf(this.config.logLevel))
+            return;
+        const extra = meta === undefined ? "" : " " + redact(meta instanceof Error ? meta.message : meta, this.secrets());
+        this.stderr(`[apple-ads-mcp ${level}] ${redact(message, this.secrets())}${extra}`);
+    }
+    async buildApi() {
+        const c = this.config;
+        const missing = missingCredentials(c);
+        if (missing.length) {
+            throw new ConfigError(`Apple Ads credentials are not configured. Missing environment variable(s): ${missing.join("; ")}.`, "Set them in your MCP client config (env block) or a .env file. See the README section 'Create Apple Ads API credentials'.");
+        }
+        let keyPath = c.privateKeyPath;
+        let tmpDir;
+        if (keyPath) {
+            if (!fs.existsSync(keyPath)) {
+                throw new ConfigError(`Private key file not found: ${keyPath}`, "Check APPLE_ADS_PRIVATE_KEY_PATH (a leading ~ is expanded). Use an absolute path.");
+            }
+        }
+        else {
+            // Inline PEM: the SDK's 'key' mode reads a file once at construction time, so we
+            // write the key to a 0600 temp file for the duration of createAppleAdsApi() only.
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "apple-ads-key-"));
+            keyPath = path.join(tmpDir, "private-key.pem");
+            fs.writeFileSync(keyPath, c.privateKey, { mode: 0o600 });
+        }
+        try {
+            return await this.createApi({
+                authMode: "key",
+                clientId: c.clientId,
+                teamId: c.teamId,
+                keyId: c.keyId,
+                privateKeyPath: keyPath,
+                baseUrl: normalizeBaseUrl(c.baseUrl),
+                authBaseUrl: normalizeAuthBaseUrl(c.tokenUrl),
+                apiTimeout: c.timeoutMs,
+                authTimeout: c.timeoutMs,
+                // The SDK's default logger is `console`, which writes to stdout and would corrupt
+                // the stdio MCP stream. Route everything to stderr, redacted.
+                logger: {
+                    debug: (m, meta) => this.log("debug", m, meta),
+                    info: (m, meta) => this.log("info", m, meta),
+                    warn: (m, meta) => this.log("warn", m, meta),
+                    error: (m, meta) => this.log("error", m, meta),
+                },
+                requestLogLevel: "debug",
+                errorLogLevel: "debug",
+                apiAxiosCustomizer: (instance) => {
+                    // Registered before the SDK's own interceptors, so it sees the raw axios
+                    // response/error (with headers) before the SDK flattens errors.
+                    instance.interceptors.response.use((res) => {
+                        this.observe(res.headers, res.status);
+                        return res;
+                    }, (err) => {
+                        if (err?.response)
+                            this.observe(err.response.headers, err.response.status);
+                        return Promise.reject(err);
+                    });
+                },
+            });
+        }
+        finally {
+            if (tmpDir) {
+                try {
+                    fs.unlinkSync(keyPath);
+                    fs.rmdirSync(tmpDir);
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+        }
+    }
+    // ───────────────────────── rate limiting ─────────────────────────
+    /** Record RateLimit-* / Retry-After headers from any response. */
+    observe(headers, status) {
+        const now = this.now();
+        const limit = Number(headerValue(headers, "RateLimit-Limit"));
+        const remaining = Number(headerValue(headers, "RateLimit-Remaining"));
+        const reset = Number(headerValue(headers, "RateLimit-Reset"));
+        if (Number.isFinite(limit))
+            this.rate.limit = limit;
+        if (Number.isFinite(remaining))
+            this.rate.remaining = remaining;
+        if (Number.isFinite(reset))
+            this.rate.resetAtMs = now + reset * 1000;
+        this.rate.observedAtMs = now;
+        if (status === 429) {
+            const retryAfter = parseRetryAfter(headerValue(headers, "Retry-After"), now);
+            const resetMs = Number.isFinite(reset) ? reset * 1000 : undefined;
+            this.rate.last429 = { atMs: now, retryAfterMs: retryAfter ?? resetMs };
+        }
+    }
+    async throttle() {
+        if (!this.config.proactiveThrottle)
+            return;
+        const { remaining, resetAtMs } = this.rate;
+        if (remaining !== undefined && remaining <= 0 && resetAtMs !== undefined) {
+            const wait = resetAtMs - this.now();
+            if (wait > 0) {
+                const capped = Math.min(wait, 30_000);
+                this.log("info", `rate limit window exhausted; pausing ${capped}ms`);
+                await this.sleep(capped);
+            }
+        }
+    }
+    backoffMs(attempt) {
+        const { retryBaseMs, retryMaxMs } = this.config;
+        return Math.min(retryBaseMs * 2 ** attempt, retryMaxMs);
+    }
+    /**
+     * Run `fn` with 429 / 5xx / network retries.
+     * - 401 is handled inside the SDK (token refresh + one retry).
+     * - 429 always retries, honouring Retry-After (then RateLimit-Reset, then capped exponential backoff).
+     * - 5xx and transient network errors retry only when `idempotent`.
+     */
+    async withRetries(fn, opts) {
+        const max = this.config.maxRetries;
+        for (let attempt = 0;; attempt++) {
+            await this.throttle();
+            const startedAt = this.now();
+            try {
+                return await fn();
+            }
+            catch (e) {
+                const err = e;
+                const isApi = e instanceof ApiRequestError || err?.name === "ApiRequestError";
+                if (!isApi || attempt >= max)
+                    throw e;
+                let wait;
+                if (err.status === 429) {
+                    const rl = this.rate.last429;
+                    const hinted = rl && rl.atMs >= startedAt ? rl.retryAfterMs : undefined;
+                    // Retry-After (or RateLimit-Reset) is authoritative; otherwise capped exponential backoff.
+                    wait = hinted !== undefined ? Math.min(hinted, 120_000) : this.backoffMs(attempt);
+                }
+                else if (opts.idempotent && err.status !== undefined && err.status >= 500 && err.status !== 501) {
+                    wait = this.backoffMs(attempt);
+                }
+                else if (opts.idempotent && err.status === undefined && err.code && NETWORK_RETRY_CODES.has(err.code)) {
+                    wait = this.backoffMs(attempt);
+                }
+                if (wait === undefined)
+                    throw e;
+                this.log("warn", `retrying after ${err.status ?? err.code} (attempt ${attempt + 1}/${max}) in ${wait}ms`);
+                await this.sleep(wait);
+                // The wait already covered the exhausted window; do not pause a second time proactively.
+                if (err.status === 429)
+                    this.rate.remaining = undefined;
+            }
+        }
+    }
+    // ───────────────────────── SDK invocation ─────────────────────────
+    /** Call an SDK operation by its method name with positional SDK arguments. */
+    async invoke(operationId, args, opts) {
+        const api = await this.getApi();
+        const fn = api[operationId];
+        if (typeof fn !== "function")
+            throw new AppleAdsToolError(`SDK operation ${operationId} does not exist`, { code: "UNKNOWN_OPERATION" });
+        const res = (await this.withRetries(() => fn.apply(api, args), opts));
+        return { status: res.status, data: res.data };
+    }
+    /** Raw authenticated request through the SDK's axios instance (auth + 401 refresh + error mapping included). */
+    async raw(method, apiPath, o) {
+        const api = await this.getApi();
+        const a = api;
+        const idempotent = ["GET", "PUT", "DELETE", "HEAD"].includes(method) || (method === "POST" && /\/query$/.test(apiPath));
+        const headers = { Accept: "application/json" };
+        if (o.context)
+            headers["X-Ap-Context"] = o.context;
+        if (o.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        const res = await this.withRetries(() => a.axios.request({
+            method,
+            url: a.basePath.replace(/\/+$/, "") + apiPath,
+            params: o.query,
+            data: o.body,
+            headers,
+        }), { idempotent });
+        return { status: res.status, data: res.data };
+    }
+    // ───────────────────────── context resolution ─────────────────────────
+    /** "123" -> "adAccountId=123"; an explicit "adAccountId=123" / "orgId=..." string passes through. */
+    static formatContext(id) {
+        const s = String(id).trim();
+        return s.includes("=") ? s.replace(/;+\s*$/, "") : `adAccountId=${s}`;
+    }
+    /** Extract the numeric/string ad account id from a context header value. */
+    static adAccountIdFromContext(ctx) {
+        if (!ctx)
+            return undefined;
+        const m = ctx.match(/adAccountId\s*=\s*([^;,\s]+)/);
+        return m ? m[1] : undefined;
+    }
+    /** Ad accounts the API user can access (GET /acls), cached for 5 minutes. */
+    async listAdAccounts() {
+        const nowMs = this.now();
+        if (!this.aclPromise || nowMs - this.aclPromise.at > 5 * 60_000) {
+            const p = this.invoke("getUserAcls", [], { idempotent: true }).then((res) => {
+                const acls = (res.data?.result?.acls ?? []);
+                return acls
+                    .filter((a) => a.adAccount?.id !== undefined)
+                    .map((a) => ({
+                    id: String(a.adAccount?.id),
+                    name: a.adAccount?.name,
+                    orgId: a.adAccount?.orgId !== undefined ? String(a.adAccount.orgId) : undefined,
+                }));
+            });
+            p.catch(() => {
+                if (this.aclPromise?.p === p)
+                    this.aclPromise = undefined;
+            });
+            this.aclPromise = { at: nowMs, p };
+        }
+        return this.aclPromise.p;
+    }
+    /**
+     * Resolve the X-AP-Context header value.
+     * explicit arg -> APPLE_ADS_AD_ACCOUNT_ID -> (if `required`) the only accessible ad account
+     * (narrowed by APPLE_ADS_ORG_ID when set).
+     */
+    async resolveContext(adAccountId, required) {
+        const explicit = adAccountId ?? this.config.adAccountId;
+        if (explicit !== undefined && String(explicit).trim() !== "")
+            return AppleAdsClient.formatContext(explicit);
+        if (!required)
+            return undefined;
+        const all = await this.listAdAccounts();
+        const candidates = this.config.orgId ? all.filter((a) => !a.orgId || a.orgId === this.config.orgId) : all;
+        if (candidates.length === 1)
+            return AppleAdsClient.formatContext(candidates[0].id);
+        const list = candidates.map((a) => `${a.id}${a.name ? ` (${a.name})` : ""}`).join(", ");
+        if (candidates.length === 0) {
+            throw new AppleAdsToolError("No ad account is accessible to this API user, so no X-AP-Context can be chosen.", {
+                code: "NO_AD_ACCOUNT",
+                hint: "Create an ad account (apple_ads_create_ad_account) or ask an Apple Ads admin to grant your API user access, then set APPLE_ADS_AD_ACCOUNT_ID.",
+            });
+        }
+        throw new AppleAdsToolError(`This API user can access several ad accounts: ${list}. Pass adAccountId or set APPLE_ADS_AD_ACCOUNT_ID.`, {
+            code: "AMBIGUOUS_AD_ACCOUNT",
+            details: { adAccounts: candidates },
+        });
+    }
+    /** orgId argument -> APPLE_ADS_ORG_ID -> orgId from GET /me. */
+    async resolveOrgId(orgId) {
+        const explicit = orgId ?? this.config.orgId;
+        if (explicit !== undefined && String(explicit).trim() !== "")
+            return String(explicit);
+        if (!this.mePromise) {
+            const p = this.invoke("getMe", [], { idempotent: true }).then((r) => {
+                const result = r.data?.result ?? {};
+                return { userId: result.userId !== undefined ? String(result.userId) : undefined, orgId: result.orgId !== undefined ? String(result.orgId) : undefined };
+            });
+            p.catch(() => {
+                if (this.mePromise === p)
+                    this.mePromise = undefined;
+            });
+            this.mePromise = p;
+        }
+        const me = await this.mePromise;
+        if (!me.orgId)
+            throw new AppleAdsToolError("Could not determine the orgId from GET /me. Pass orgId explicitly.", { code: "NO_ORG" });
+        return me.orgId;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,47 @@
+/** Names of every tool group. Kept in sync with scripts/curated.mjs (checked by tests). */
+export declare const GROUP_NAMES: readonly ["accounts", "apps", "eligibility", "brands", "location_groups", "campaigns", "ad_groups", "ads", "creatives", "assets", "keywords", "negative_keywords", "bulk", "geo", "product_pages", "budget_orders", "reports_apps", "reports_brands", "insights", "recommendations", "suggestions", "change_history", "meta"];
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+export interface ServerConfig {
+    clientId?: string;
+    teamId?: string;
+    keyId?: string;
+    /** Path to the .pem private key (~ expanded). */
+    privateKeyPath?: string;
+    /** Inline PEM private key (alternative to a path). */
+    privateKey?: string;
+    /** Default ad account (X-AP-Context: adAccountId=...). */
+    adAccountId?: string;
+    /** Default organization. Used by apple_ads_get_org and to narrow ad account auto-discovery. */
+    orgId?: string;
+    readOnly: boolean;
+    enabledGroups?: string[];
+    disabledGroups: string[];
+    /** TEST-ONLY: override https://api.ads.apple.com/v1 */
+    baseUrl?: string;
+    /** TEST-ONLY: override https://appleid.apple.com/ (or the full token URL). */
+    tokenUrl?: string;
+    timeoutMs: number;
+    maxRetries: number;
+    retryBaseMs: number;
+    retryMaxMs: number;
+    proactiveThrottle: boolean;
+    logLevel: LogLevel;
+}
+export interface LoadedConfig {
+    config: ServerConfig;
+    /** Environment variables that must be set for API calls to work (empty when fully configured). */
+    missing: string[];
+    /** Non-fatal configuration problems (unknown group names, bad numbers, ...). */
+    problems: string[];
+}
+type Env = Record<string, string | undefined>;
+export declare function parseGroupList(raw: string | undefined, problems: string[], varName: string): string[] | undefined;
+/** Expand a leading ~ to the home directory. */
+export declare function expandHome(p: string): string;
+/** Normalise a PEM supplied through an environment variable (handles literal "\n"). */
+export declare function normalizePem(raw: string): string;
+export declare function loadConfig(env?: Env): LoadedConfig;
+/** Human-readable list of the env vars still needed (primary names with aliases). */
+export declare function missingCredentials(c: Pick<ServerConfig, "clientId" | "teamId" | "keyId" | "privateKeyPath" | "privateKey">): string[];
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,2FAA2F;AAC3F,eAAO,MAAM,WAAW,+TAwBd,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,kGAAkG;IAClG,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gFAAgF;IAChF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AA2B9C,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAYjH;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI5C;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,wBAAgB,UAAU,CAAC,GAAG,GAAE,GAAiB,GAAG,YAAY,CAwC/D;AAED,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,gBAAgB,GAAG,YAAY,CAAC,GAAG,MAAM,EAAE,CASrI"}