@cesteral/tiktok-mcp 1.0.0

package/dist/mcp-server/tools/definitions/search-targeting.tool.d.ts

@@ -0,0 +1,131 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const SearchTargetingInputSchema: z.ZodObject<{
+    advertiserId: z.ZodString;
+    query: z.ZodString;
+    scene: z.ZodDefault<z.ZodOptional<z.ZodEnum<["GEO", "ISP"]>>>;
+    placements: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    objectiveType: z.ZodOptional<z.ZodString>;
+    promotionType: z.ZodOptional<z.ZodString>;
+    operatingSystem: z.ZodOptional<z.ZodEnum<["ANDROID", "IOS"]>>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    advertiserId: string;
+    query: string;
+    scene: "ISP" | "GEO";
+    limit: number;
+    placements?: string[] | undefined;
+    objectiveType?: string | undefined;
+    promotionType?: string | undefined;
+    operatingSystem?: "ANDROID" | "IOS" | undefined;
+}, {
+    advertiserId: string;
+    query: string;
+    scene?: "ISP" | "GEO" | undefined;
+    placements?: string[] | undefined;
+    objectiveType?: string | undefined;
+    promotionType?: string | undefined;
+    operatingSystem?: "ANDROID" | "IOS" | undefined;
+    limit?: number | undefined;
+}>;
+export declare const SearchTargetingOutputSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">;
+    count: z.ZodNumber;
+    targetingType: z.ZodString;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    results: Record<string, any>[];
+    count: number;
+    timestamp: string;
+    targetingType: string;
+}, {
+    results: Record<string, any>[];
+    count: number;
+    timestamp: string;
+    targetingType: string;
+}>;
+type SearchTargetingInput = z.infer<typeof SearchTargetingInputSchema>;
+type SearchTargetingOutput = z.infer<typeof SearchTargetingOutputSchema>;
+export declare function searchTargetingLogic(input: SearchTargetingInput, context: RequestContext, sdkContext?: SdkContext): Promise<SearchTargetingOutput>;
+export declare function searchTargetingResponseFormatter(result: SearchTargetingOutput): McpTextContent[];
+export declare const searchTargetingTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        advertiserId: z.ZodString;
+        query: z.ZodString;
+        scene: z.ZodDefault<z.ZodOptional<z.ZodEnum<["GEO", "ISP"]>>>;
+        placements: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        objectiveType: z.ZodOptional<z.ZodString>;
+        promotionType: z.ZodOptional<z.ZodString>;
+        operatingSystem: z.ZodOptional<z.ZodEnum<["ANDROID", "IOS"]>>;
+        limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        advertiserId: string;
+        query: string;
+        scene: "ISP" | "GEO";
+        limit: number;
+        placements?: string[] | undefined;
+        objectiveType?: string | undefined;
+        promotionType?: string | undefined;
+        operatingSystem?: "ANDROID" | "IOS" | undefined;
+    }, {
+        advertiserId: string;
+        query: string;
+        scene?: "ISP" | "GEO" | undefined;
+        placements?: string[] | undefined;
+        objectiveType?: string | undefined;
+        promotionType?: string | undefined;
+        operatingSystem?: "ANDROID" | "IOS" | undefined;
+        limit?: number | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        results: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">;
+        count: z.ZodNumber;
+        targetingType: z.ZodString;
+        timestamp: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        results: Record<string, any>[];
+        count: number;
+        timestamp: string;
+        targetingType: string;
+    }, {
+        results: Record<string, any>[];
+        count: number;
+        timestamp: string;
+        targetingType: string;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        idempotentHint: boolean;
+        destructiveHint: boolean;
+    };
+    inputExamples: ({
+        label: string;
+        input: {
+            advertiserId: string;
+            query: string;
+            scene: string;
+            placements: string[];
+            objectiveType: string;
+            limit: number;
+        };
+    } | {
+        label: string;
+        input: {
+            advertiserId: string;
+            query: string;
+            scene: string;
+            limit: number;
+            placements?: undefined;
+            objectiveType?: undefined;
+        };
+    })[];
+    logic: typeof searchTargetingLogic;
+    responseFormatter: typeof searchTargetingResponseFormatter;
+};
+export {};
+//# sourceMappingURL=search-targeting.tool.d.ts.map

package/dist/mcp-server/tools/definitions/search-targeting.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-targeting.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-targeting.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAcnD,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoCyB,CAAC;AAEjE,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;EAOF,CAAC;AAEvC,KAAK,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AACvE,KAAK,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEzE,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,qBAAqB,CAAC,CA0BhC;AAED,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,qBAAqB,GAAG,cAAc,EAAE,CAOhG;AAED,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoC/B,CAAC"}

package/dist/mcp-server/tools/definitions/search-targeting.tool.js

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+const TOOL_NAME = "tiktok_search_targeting";
+const TOOL_TITLE = "TikTok Search Targeting Options";
+const TOOL_DESCRIPTION = `Search TikTok location-style targeting tags using TikTok's official \`/tool/targeting/search/\` endpoint.
+
+This endpoint is for targeting-tag discovery, not general interest/language browsing.
+Use \`tiktok_get_targeting_options\` for official list endpoints such as languages, carriers,
+interest categories, device models, and geographic options.
+
+**Common scenes:**
+- \`GEO\` — Geo targeting tags such as regions, zip codes, or postal codes
+- \`ISP\` — Internet service provider targeting tags`;
+export const SearchTargetingInputSchema = z
+    .object({
+    advertiserId: z.string().min(1).describe("TikTok Advertiser ID"),
+    query: z.string().min(1).describe("Search keyword passed to TikTok targeting search"),
+    scene: z
+        .enum(["GEO", "ISP"])
+        .optional()
+        .default("GEO")
+        .describe("Targeting tag scene to search"),
+    placements: z
+        .array(z.string())
+        .optional()
+        .describe("Placements required by TikTok for GEO searches, e.g. ['PLACEMENT_TIKTOK']"),
+    objectiveType: z
+        .string()
+        .optional()
+        .describe("Objective type required by TikTok for GEO searches, e.g. TRAFFIC or APP_PROMOTION"),
+    promotionType: z
+        .string()
+        .optional()
+        .describe("Promotion type used for GEO searches when required by the selected objective"),
+    operatingSystem: z
+        .enum(["ANDROID", "IOS"])
+        .optional()
+        .describe("Optional OS filter for GEO searches"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .optional()
+        .default(20)
+        .describe("Maximum number of results to request from TikTok"),
+})
+    .describe("Parameters for searching TikTok targeting options");
+export const SearchTargetingOutputSchema = z
+    .object({
+    results: z.array(z.record(z.any())).describe("Targeting options matching the query"),
+    count: z.number().describe("Number of results returned"),
+    targetingType: z.string(),
+    timestamp: z.string().datetime(),
+})
+    .describe("Targeting search result");
+export async function searchTargetingLogic(input, context, sdkContext) {
+    const { tiktokService } = resolveSessionServices(sdkContext);
+    const results = (await tiktokService.searchTargeting({
+        keyword: input.query,
+        scene: input.scene,
+        ...(input.placements ? { placements: input.placements } : {}),
+        ...(input.objectiveType ? { objective_type: input.objectiveType } : {}),
+        ...(input.promotionType ? { promotion_type: input.promotionType } : {}),
+        ...(input.operatingSystem ? { operating_system: input.operatingSystem } : {}),
+        page_size: input.limit,
+    }, context));
+    const list = Array.isArray(results)
+        ? results
+        : (results.list ?? []);
+    return {
+        results: list,
+        count: list.length,
+        targetingType: input.scene,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function searchTargetingResponseFormatter(result) {
+    return [
+        {
+            type: "text",
+            text: `Found ${result.count} ${result.targetingType} targeting options\n${JSON.stringify(result.results, null, 2)}\n\nTimestamp: ${result.timestamp}`,
+        },
+    ];
+}
+export const searchTargetingTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: SearchTargetingInputSchema,
+    outputSchema: SearchTargetingOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+        idempotentHint: true,
+        destructiveHint: false,
+    },
+    inputExamples: [
+        {
+            label: "Search geo targeting tags",
+            input: {
+                advertiserId: "1234567890",
+                query: "stockholm",
+                scene: "GEO",
+                placements: ["PLACEMENT_TIKTOK"],
+                objectiveType: "TRAFFIC",
+                limit: 20,
+            },
+        },
+        {
+            label: "Search ISP targeting tags",
+            input: {
+                advertiserId: "1234567890",
+                query: "telia",
+                scene: "ISP",
+                limit: 30,
+            },
+        },
+    ],
+    logic: searchTargetingLogic,
+    responseFormatter: searchTargetingResponseFormatter,
+};
+//# sourceMappingURL=search-targeting.tool.js.map

package/dist/mcp-server/tools/definitions/search-targeting.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-targeting.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-targeting.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAIrE,MAAM,SAAS,GAAG,yBAAyB,CAAC;AAC5C,MAAM,UAAU,GAAG,iCAAiC,CAAC;AACrD,MAAM,gBAAgB,GAAG;;;;;;;;qDAQ4B,CAAC;AAEtD,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC;KACxC,MAAM,CAAC;IACN,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IAChE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,kDAAkD,CAAC;IACrF,KAAK,EAAE,CAAC;SACL,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;SACpB,QAAQ,EAAE;SACV,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,+BAA+B,CAAC;IAC5C,UAAU,EAAE,CAAC;SACV,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,QAAQ,EAAE;SACV,QAAQ,CAAC,2EAA2E,CAAC;IACxF,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,mFAAmF,CACpF;IACH,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,8EAA8E,CAAC;IAC3F,eAAe,EAAE,CAAC;SACf,IAAI,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;SACxB,QAAQ,EAAE;SACV,QAAQ,CAAC,qCAAqC,CAAC;IAClD,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,IAAI,CAAC;SACT,QAAQ,EAAE;SACV,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,kDAAkD,CAAC;CAChE,CAAC;KACD,QAAQ,CAAC,mDAAmD,CAAC,CAAC;AAEjE,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC;KACzC,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,sCAAsC,CAAC;IACpF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACxD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC;KACD,QAAQ,CAAC,yBAAyB,CAAC,CAAC;AAKvC,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAA2B,EAC3B,OAAuB,EACvB,UAAuB;IAEvB,MAAM,EAAE,aAAa,EAAE,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;IAE7D,MAAM,OAAO,GAAG,CAAC,MAAM,aAAa,CAAC,eAAe,CAClD;QACE,OAAO,EAAE,KAAK,CAAC,KAAK;QACpB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,SAAS,EAAE,KAAK,CAAC,KAAK;KACvB,EACD,OAAO,CACR,CAAqE,CAAC;IAEvE,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QACjC,CAAC,CAAC,OAAO;QACT,CAAC,CAAC,CAAE,OAAgD,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAEnE,OAAO;QACL,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,IAAI,CAAC,MAAM;QAClB,aAAa,EAAE,KAAK,CAAC,KAAK;QAC1B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gCAAgC,CAAC,MAA6B;IAC5E,OAAO;QACL;YACE,IAAI,EAAE,MAAe;YACrB,IAAI,EAAE,SAAS,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,aAAa,uBAAuB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,kBAAkB,MAAM,CAAC,SAAS,EAAE;SACtJ;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,UAAU;IACjB,WAAW,EAAE,gBAAgB;IAC7B,WAAW,EAAE,0BAA0B;IACvC,YAAY,EAAE,2BAA2B;IACzC,WAAW,EAAE;QACX,YAAY,EAAE,IAAI;QAClB,aAAa,EAAE,KAAK;QACpB,cAAc,EAAE,IAAI;QACpB,eAAe,EAAE,KAAK;KACvB;IACD,aAAa,EAAE;QACb;YACE,KAAK,EAAE,2BAA2B;YAClC,KAAK,EAAE;gBACL,YAAY,EAAE,YAAY;gBAC1B,KAAK,EAAE,WAAW;gBAClB,KAAK,EAAE,KAAK;gBACZ,UAAU,EAAE,CAAC,kBAAkB,CAAC;gBAChC,aAAa,EAAE,SAAS;gBACxB,KAAK,EAAE,EAAE;aACV;SACF;QACD;YACE,KAAK,EAAE,2BAA2B;YAClC,KAAK,EAAE;gBACL,YAAY,EAAE,YAAY;gBAC1B,KAAK,EAAE,OAAO;gBACd,KAAK,EAAE,KAAK;gBACZ,KAAK,EAAE,EAAE;aACV;SACF;KACF;IACD,KAAK,EAAE,oBAAoB;IAC3B,iBAAiB,EAAE,gCAAgC;CACpD,CAAC"}

package/dist/mcp-server/tools/definitions/submit-report.tool.d.ts

@@ -0,0 +1,153 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const SubmitReportInputSchema: z.ZodEffects<z.ZodObject<{
+    advertiserId: z.ZodString;
+    reportType: z.ZodDefault<z.ZodOptional<z.ZodEnum<["BASIC", "AUDIENCE", "PLAYABLE_MATERIAL"]>>>;
+    dimensions: z.ZodArray<z.ZodString, "many">;
+    metrics: z.ZodArray<z.ZodString, "many">;
+    datePreset: z.ZodOptional<z.ZodEnum<["TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH", "LAST_90_DAYS"]>>;
+    startDate: z.ZodOptional<z.ZodString>;
+    endDate: z.ZodOptional<z.ZodString>;
+    orderField: z.ZodOptional<z.ZodString>;
+    orderType: z.ZodOptional<z.ZodEnum<["ASC", "DESC"]>>;
+}, "strip", z.ZodTypeAny, {
+    dimensions: string[];
+    metrics: string[];
+    advertiserId: string;
+    reportType: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL";
+    datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+    startDate?: string | undefined;
+    endDate?: string | undefined;
+    orderField?: string | undefined;
+    orderType?: "ASC" | "DESC" | undefined;
+}, {
+    dimensions: string[];
+    metrics: string[];
+    advertiserId: string;
+    reportType?: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL" | undefined;
+    datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+    startDate?: string | undefined;
+    endDate?: string | undefined;
+    orderField?: string | undefined;
+    orderType?: "ASC" | "DESC" | undefined;
+}>, {
+    dimensions: string[];
+    metrics: string[];
+    advertiserId: string;
+    reportType: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL";
+    datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+    startDate?: string | undefined;
+    endDate?: string | undefined;
+    orderField?: string | undefined;
+    orderType?: "ASC" | "DESC" | undefined;
+}, {
+    dimensions: string[];
+    metrics: string[];
+    advertiserId: string;
+    reportType?: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL" | undefined;
+    datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+    startDate?: string | undefined;
+    endDate?: string | undefined;
+    orderField?: string | undefined;
+    orderType?: "ASC" | "DESC" | undefined;
+}>;
+export declare const SubmitReportOutputSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    taskId: string;
+    timestamp: string;
+}, {
+    taskId: string;
+    timestamp: string;
+}>;
+type SubmitReportInput = z.infer<typeof SubmitReportInputSchema>;
+type SubmitReportOutput = z.infer<typeof SubmitReportOutputSchema>;
+export declare function submitReportLogic(input: SubmitReportInput, context: RequestContext, sdkContext?: SdkContext): Promise<SubmitReportOutput>;
+export declare function submitReportResponseFormatter(result: SubmitReportOutput): McpTextContent[];
+export declare const submitReportTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodEffects<z.ZodObject<{
+        advertiserId: z.ZodString;
+        reportType: z.ZodDefault<z.ZodOptional<z.ZodEnum<["BASIC", "AUDIENCE", "PLAYABLE_MATERIAL"]>>>;
+        dimensions: z.ZodArray<z.ZodString, "many">;
+        metrics: z.ZodArray<z.ZodString, "many">;
+        datePreset: z.ZodOptional<z.ZodEnum<["TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH", "LAST_90_DAYS"]>>;
+        startDate: z.ZodOptional<z.ZodString>;
+        endDate: z.ZodOptional<z.ZodString>;
+        orderField: z.ZodOptional<z.ZodString>;
+        orderType: z.ZodOptional<z.ZodEnum<["ASC", "DESC"]>>;
+    }, "strip", z.ZodTypeAny, {
+        dimensions: string[];
+        metrics: string[];
+        advertiserId: string;
+        reportType: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL";
+        datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        orderField?: string | undefined;
+        orderType?: "ASC" | "DESC" | undefined;
+    }, {
+        dimensions: string[];
+        metrics: string[];
+        advertiserId: string;
+        reportType?: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL" | undefined;
+        datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        orderField?: string | undefined;
+        orderType?: "ASC" | "DESC" | undefined;
+    }>, {
+        dimensions: string[];
+        metrics: string[];
+        advertiserId: string;
+        reportType: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL";
+        datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        orderField?: string | undefined;
+        orderType?: "ASC" | "DESC" | undefined;
+    }, {
+        dimensions: string[];
+        metrics: string[];
+        advertiserId: string;
+        reportType?: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL" | undefined;
+        datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        orderField?: string | undefined;
+        orderType?: "ASC" | "DESC" | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        taskId: z.ZodString;
+        timestamp: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        taskId: string;
+        timestamp: string;
+    }, {
+        taskId: string;
+        timestamp: string;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+    };
+    inputExamples: {
+        label: string;
+        input: {
+            advertiserId: string;
+            dimensions: string[];
+            metrics: string[];
+            datePreset: string;
+        };
+    }[];
+    logic: typeof submitReportLogic;
+    responseFormatter: typeof submitReportResponseFormatter;
+};
+export {};
+//# sourceMappingURL=submit-report.tool.d.ts.map

package/dist/mcp-server/tools/definitions/submit-report.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit-report.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/submit-report.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAenD,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2CwB,CAAC;AAE7D,eAAO,MAAM,wBAAwB;;;;;;;;;EAKE,CAAC;AAExC,KAAK,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACjE,KAAK,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEnE,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,kBAAkB,CAAC,CA4B7B;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,kBAAkB,GAAG,cAAc,EAAE,CAO1F;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyB5B,CAAC"}

package/dist/mcp-server/tools/definitions/submit-report.tool.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+import { resolveDatePreset, DATE_PRESET_VALUES } from "@cesteral/shared";
+const TOOL_NAME = "tiktok_submit_report";
+const TOOL_TITLE = "Submit TikTok Report";
+const TOOL_DESCRIPTION = `Submit a TikTok Ads report task without waiting for completion.
+
+Returns a \`taskId\` immediately. Use \`tiktok_check_report_status\` to poll for completion, then \`tiktok_download_report\` to fetch results.
+
+**Non-blocking workflow:**
+1. \`tiktok_submit_report\` → get \`taskId\`
+2. \`tiktok_check_report_status\` (repeat every 10s) → wait for "DONE"
+3. \`tiktok_download_report\` with the \`downloadUrl\` → get parsed data
+
+Use \`tiktok_get_report\` instead for a blocking convenience shortcut.`;
+export const SubmitReportInputSchema = z
+    .object({
+    advertiserId: z
+        .string()
+        .min(1)
+        .describe("TikTok Advertiser ID (informational — the session-bound advertiser from authentication is used for API calls)"),
+    reportType: z
+        .enum(["BASIC", "AUDIENCE", "PLAYABLE_MATERIAL"])
+        .optional()
+        .default("BASIC")
+        .describe("Report type (default: BASIC)"),
+    dimensions: z
+        .array(z.string())
+        .min(1)
+        .describe("Dimensions for the report (e.g., ['campaign_id', 'stat_time_day'])"),
+    metrics: z
+        .array(z.string())
+        .min(1)
+        .describe("Metrics to include (e.g., ['impressions', 'clicks', 'spend'])"),
+    datePreset: z
+        .enum(DATE_PRESET_VALUES)
+        .optional()
+        .describe("Preset date range. Use this OR startDate+endDate (not both)"),
+    startDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .describe("Start date (YYYY-MM-DD, required if datePreset not provided)"),
+    endDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .describe("End date (YYYY-MM-DD, required if datePreset not provided)"),
+    orderField: z.string().optional().describe("Field to order results by"),
+    orderType: z.enum(["ASC", "DESC"]).optional().describe("Sort order"),
+})
+    .refine((data) => data.datePreset !== undefined || (data.startDate !== undefined && data.endDate !== undefined), { message: "Provide either datePreset or both startDate and endDate" })
+    .describe("Parameters for submitting a TikTok Ads report");
+export const SubmitReportOutputSchema = z
+    .object({
+    taskId: z.string().describe("Report task ID for status polling"),
+    timestamp: z.string().datetime(),
+})
+    .describe("Report submission result");
+export async function submitReportLogic(input, context, sdkContext) {
+    const { tiktokReportingService } = resolveSessionServices(sdkContext);
+    let resolvedStartDate = input.startDate;
+    let resolvedEndDate = input.endDate;
+    if (input.datePreset) {
+        const resolved = resolveDatePreset(input.datePreset);
+        resolvedStartDate = resolved.startDate;
+        resolvedEndDate = resolved.endDate;
+    }
+    const result = await tiktokReportingService.submitReport({
+        report_type: input.reportType,
+        dimensions: input.dimensions,
+        metrics: input.metrics,
+        start_date: resolvedStartDate,
+        end_date: resolvedEndDate,
+        ...(input.orderField ? { order_field: input.orderField } : {}),
+        ...(input.orderType ? { order_type: input.orderType } : {}),
+    }, context);
+    return {
+        taskId: result.task_id,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function submitReportResponseFormatter(result) {
+    return [
+        {
+            type: "text",
+            text: `Report submitted: ${result.taskId}\n\nUse \`tiktok_check_report_status\` with this taskId to poll for completion.\n\nTimestamp: ${result.timestamp}`,
+        },
+    ];
+}
+export const submitReportTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: SubmitReportInputSchema,
+    outputSchema: SubmitReportOutputSchema,
+    annotations: {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+    },
+    inputExamples: [
+        {
+            label: "Submit campaign performance report",
+            input: {
+                advertiserId: "1234567890",
+                dimensions: ["campaign_id", "stat_time_day"],
+                metrics: ["impressions", "clicks", "spend", "ctr", "cpc"],
+                datePreset: "LAST_7_DAYS",
+            },
+        },
+    ],
+    logic: submitReportLogic,
+    responseFormatter: submitReportResponseFormatter,
+};
+//# sourceMappingURL=submit-report.tool.js.map

package/dist/mcp-server/tools/definitions/submit-report.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit-report.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/submit-report.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/update-entity.tool.d.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const UpdateEntityInputSchema: z.ZodObject<{
+    entityType: z.ZodEnum<[string, ...string[]]>;
+    advertiserId: z.ZodString;
+    entityId: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodAny>;
+}, "strip", z.ZodTypeAny, {
+    entityType: string;
+    advertiserId: string;
+    entityId: string;
+    data: Record<string, any>;
+}, {
+    entityType: string;
+    advertiserId: string;
+    entityId: string;
+    data: Record<string, any>;
+}>;
+export declare const UpdateEntityOutputSchema: z.ZodObject<{
+    entityId: z.ZodString;
+    entityType: z.ZodString;
+    updated: z.ZodBoolean;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    entityType: string;
+    timestamp: string;
+    entityId: string;
+    updated: boolean;
+}, {
+    entityType: string;
+    timestamp: string;
+    entityId: string;
+    updated: boolean;
+}>;
+type UpdateEntityInput = z.infer<typeof UpdateEntityInputSchema>;
+type UpdateEntityOutput = z.infer<typeof UpdateEntityOutputSchema>;
+export declare function updateEntityLogic(input: UpdateEntityInput, context: RequestContext, sdkContext?: SdkContext): Promise<UpdateEntityOutput>;
+export declare function updateEntityResponseFormatter(result: UpdateEntityOutput): McpTextContent[];
+export declare const updateEntityTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        entityType: z.ZodEnum<[string, ...string[]]>;
+        advertiserId: z.ZodString;
+        entityId: z.ZodString;
+        data: z.ZodRecord<z.ZodString, z.ZodAny>;
+    }, "strip", z.ZodTypeAny, {
+        entityType: string;
+        advertiserId: string;
+        entityId: string;
+        data: Record<string, any>;
+    }, {
+        entityType: string;
+        advertiserId: string;
+        entityId: string;
+        data: Record<string, any>;
+    }>;
+    outputSchema: z.ZodObject<{
+        entityId: z.ZodString;
+        entityType: z.ZodString;
+        updated: z.ZodBoolean;
+        timestamp: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        entityType: string;
+        timestamp: string;
+        entityId: string;
+        updated: boolean;
+    }, {
+        entityType: string;
+        timestamp: string;
+        entityId: string;
+        updated: boolean;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        idempotentHint: boolean;
+        destructiveHint: boolean;
+    };
+    inputExamples: ({
+        label: string;
+        input: {
+            entityType: string;
+            advertiserId: string;
+            entityId: string;
+            data: {
+                campaign_name: string;
+                budget: number;
+                bid_price?: undefined;
+            };
+        };
+    } | {
+        label: string;
+        input: {
+            entityType: string;
+            advertiserId: string;
+            entityId: string;
+            data: {
+                bid_price: number;
+                campaign_name?: undefined;
+                budget?: undefined;
+            };
+        };
+    })[];
+    logic: typeof updateEntityLogic;
+    responseFormatter: typeof updateEntityResponseFormatter;
+};
+export {};
+//# sourceMappingURL=update-entity.tool.d.ts.map

package/dist/mcp-server/tools/definitions/update-entity.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-entity.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/update-entity.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAcnD,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;EAOsB,CAAC;AAE3D,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;EAOF,CAAC;AAEpC,KAAK,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACjE,KAAK,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEnE,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAgB7B;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,kBAAkB,GAAG,cAAc,EAAE,CAO1F;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuC5B,CAAC"}