@creatorarmy/openclaw-creatorarmy 1.0.0

package/client.ts

@@ -0,0 +1,293 @@
+import { log } from "./logger.ts"
+
+export type Reference = {
+	slug: string
+	filename: string
+	content?: string
+}
+
+export type BrandContext = {
+	_id: string
+	email?: string
+	brandName: string
+	brandUrl?: string
+	personality?: string
+	tone?: string
+	visualStyle?: string
+	icp?: string
+	customerTypes?: string[]
+	barriers?: string[]
+	motivators?: string[]
+	notes?: string
+	createdAt?: string
+	updatedAt?: string
+}
+
+export type CustomerType = {
+	name: string
+	description?: string
+	barriers?: string[]
+	motivators?: string[]
+}
+
+export type Excavation = {
+	_id: string
+	brandName: string
+	customerTypes?: CustomerType[]
+	coreProblem?: string
+	failedSolutions?: string
+	desiredOutcome?: string
+	uniqueMechanism?: string
+	notes?: string
+	createdAt?: string
+	updatedAt?: string
+}
+
+export type SellingSequence = {
+	rapport?: string
+	openLoop?: string
+	valueStack?: string
+	wowMoment?: string
+	cta?: string
+}
+
+export type Brief = {
+	_id: string
+	brandName: string
+	title: string
+	customerType?: string
+	sellingSequence?: SellingSequence
+	hooks?: string[]
+	buildingBlocks?: string[]
+	creativeType?: string
+	platform?: string
+	duration?: number
+	notes?: string
+	createdAt?: string
+	updatedAt?: string
+}
+
+export type PersuasionChecklist = {
+	ethos?: boolean
+	logos?: boolean
+	pathos?: boolean
+	metaphor?: boolean
+	brevity?: boolean
+}
+
+export type Script = {
+	_id: string
+	brandName: string
+	briefId?: string
+	title: string
+	customerType?: string
+	format?: string
+	platform?: string
+	duration?: number
+	hook?: string
+	openLoop?: string
+	body?: string
+	cta?: string
+	sellingSequence?: SellingSequence
+	buildingBlocks?: string[]
+	persuasionChecklist?: PersuasionChecklist
+	notes?: string
+	createdAt?: string
+	updatedAt?: string
+}
+
+export class CreatorArmyClient {
+	private apiKey: string
+	private baseUrl: string
+
+	constructor(apiKey: string, baseUrl: string) {
+		if (!apiKey) {
+			throw new Error("Creator Army API key is required")
+		}
+		this.apiKey = apiKey
+		this.baseUrl = baseUrl
+		log.info(`client initialized (${baseUrl})`)
+	}
+
+	private async request<T>(
+		method: string,
+		path: string,
+		body?: Record<string, unknown>,
+	): Promise<T> {
+		log.debugRequest(`${method} ${path}`, body ?? {})
+
+		const response = await fetch(`${this.baseUrl}${path}`, {
+			method,
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${this.apiKey}`,
+			},
+			...(body && { body: JSON.stringify(body) }),
+		})
+
+		if (!response.ok) {
+			const text = await response.text()
+			throw new Error(`Creator Army API error (${response.status}): ${text}`)
+		}
+
+		const data = (await response.json()) as T
+		log.debugResponse(`${method} ${path}`, data)
+		return data
+	}
+
+	// Health
+
+	async health(): Promise<{ ok: boolean; message?: string }> {
+		try {
+			const data = await this.request<{ status: string; keyPrefix?: string }>(
+				"GET",
+				"/api/plugin/health",
+			)
+			return { ok: data.status === "ok" }
+		} catch (err) {
+			return {
+				ok: false,
+				message: err instanceof Error ? err.message : "Unknown error",
+			}
+		}
+	}
+
+	// References
+
+	async listReferences(): Promise<Reference[]> {
+		const data = await this.request<{ references: Reference[] }>(
+			"GET",
+			"/api/plugin/demand-engine/references",
+		)
+		return data.references
+	}
+
+	async getReference(slug: string): Promise<Reference> {
+		return this.request<Reference>(
+			"GET",
+			`/api/plugin/demand-engine/references?ref=${encodeURIComponent(slug)}`,
+		)
+	}
+
+	// Brand Context
+
+	async listBrands(): Promise<BrandContext[]> {
+		const data = await this.request<{ brands: BrandContext[] }>(
+			"GET",
+			"/api/plugin/demand-engine/context",
+		)
+		return data.brands
+	}
+
+	async getBrandContext(brand: string): Promise<BrandContext | null> {
+		const data = await this.request<{ context: BrandContext | null }>(
+			"GET",
+			`/api/plugin/demand-engine/context?brand=${encodeURIComponent(brand)}`,
+		)
+		return data.context
+	}
+
+	async saveBrandContext(
+		context: Record<string, unknown>,
+	): Promise<BrandContext> {
+		const data = await this.request<{ context: BrandContext }>(
+			"POST",
+			"/api/plugin/demand-engine/context",
+			context,
+		)
+		return data.context
+	}
+
+	// Excavation
+
+	async getExcavation(brand: string): Promise<Excavation | null> {
+		const data = await this.request<{ excavation: Excavation | null }>(
+			"GET",
+			`/api/plugin/demand-engine/excavation?brand=${encodeURIComponent(brand)}`,
+		)
+		return data.excavation
+	}
+
+	async saveExcavation(
+		excavation: Record<string, unknown>,
+	): Promise<Excavation> {
+		const data = await this.request<{ excavation: Excavation }>(
+			"POST",
+			"/api/plugin/demand-engine/excavation",
+			excavation,
+		)
+		return data.excavation
+	}
+
+	// Briefs
+
+	async listBriefs(params?: {
+		brand?: string
+		limit?: number
+		offset?: number
+	}): Promise<{ briefs: Brief[]; total: number }> {
+		const query = new URLSearchParams()
+		if (params?.brand) query.set("brand", params.brand)
+		if (params?.limit) query.set("limit", String(params.limit))
+		if (params?.offset) query.set("offset", String(params.offset))
+		const qs = query.toString()
+		return this.request<{ briefs: Brief[]; total: number }>(
+			"GET",
+			`/api/plugin/demand-engine/briefs${qs ? `?${qs}` : ""}`,
+		)
+	}
+
+	async getBrief(id: string): Promise<Brief | null> {
+		const data = await this.request<{ brief: Brief | null }>(
+			"GET",
+			`/api/plugin/demand-engine/briefs?id=${encodeURIComponent(id)}`,
+		)
+		return data.brief
+	}
+
+	async saveBrief(brief: Record<string, unknown>): Promise<Brief> {
+		const data = await this.request<{ brief: Brief }>(
+			"POST",
+			"/api/plugin/demand-engine/briefs",
+			brief,
+		)
+		return data.brief
+	}
+
+	// Scripts
+
+	async listScripts(params?: {
+		brand?: string
+		briefId?: string
+		limit?: number
+		offset?: number
+	}): Promise<{ scripts: Script[]; total: number }> {
+		const query = new URLSearchParams()
+		if (params?.brand) query.set("brand", params.brand)
+		if (params?.briefId) query.set("briefId", params.briefId)
+		if (params?.limit) query.set("limit", String(params.limit))
+		if (params?.offset) query.set("offset", String(params.offset))
+		const qs = query.toString()
+		return this.request<{ scripts: Script[]; total: number }>(
+			"GET",
+			`/api/plugin/demand-engine/scripts${qs ? `?${qs}` : ""}`,
+		)
+	}
+
+	async getScript(id: string): Promise<Script | null> {
+		const data = await this.request<{ script: Script | null }>(
+			"GET",
+			`/api/plugin/demand-engine/scripts?id=${encodeURIComponent(id)}`,
+		)
+		return data.script
+	}
+
+	async saveScript(script: Record<string, unknown>): Promise<Script> {
+		const data = await this.request<{ script: Script }>(
+			"POST",
+			"/api/plugin/demand-engine/scripts",
+			script,
+		)
+		return data.script
+	}
+}

package/commands/cli.ts

@@ -0,0 +1,108 @@
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+import * as readline from "node:readline"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { CreatorArmyClient } from "../client.ts"
+import type { CreatorArmyConfig } from "../config.ts"
+import { parseConfig } from "../config.ts"
+import { registerHealthCommand } from "./health.ts"
+
+export function registerCliSetup(api: OpenClawPluginApi): void {
+	api.registerCli(
+		// biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
+		({ program }: { program: any }) => {
+			const cmd = program
+				.command("creator-army")
+				.description("Creator Army plugin commands")
+
+			cmd
+				.command("setup")
+				.description("Configure Creator Army API key")
+				.action(async () => {
+					const configDir = path.join(os.homedir(), ".openclaw")
+					const configPath = path.join(configDir, "openclaw.json")
+
+					console.log("\nCreator Army Setup\n")
+					console.log("Enter your Creator Army API key:\n")
+
+					const rl = readline.createInterface({
+						input: process.stdin,
+						output: process.stdout,
+					})
+
+					const apiKey = await new Promise<string>((resolve) => {
+						rl.question("API key: ", resolve)
+					})
+					rl.close()
+
+					if (!apiKey.trim()) {
+						console.log("\nNo API key provided. Setup cancelled.")
+						return
+					}
+
+					let config: Record<string, unknown> = {}
+					if (fs.existsSync(configPath)) {
+						try {
+							config = JSON.parse(fs.readFileSync(configPath, "utf-8"))
+						} catch {
+							config = {}
+						}
+					}
+
+					if (!config.plugins) config.plugins = {}
+					const plugins = config.plugins as Record<string, unknown>
+					if (!plugins.entries) plugins.entries = {}
+					const entries = plugins.entries as Record<string, unknown>
+
+					entries["openclaw-creatorarmy"] = {
+						enabled: true,
+						config: {
+							apiKey: apiKey.trim(),
+						},
+					}
+
+					if (!fs.existsSync(configDir)) {
+						fs.mkdirSync(configDir, { recursive: true })
+					}
+
+					fs.writeFileSync(configPath, JSON.stringify(config, null, 2))
+
+					console.log("\nAPI key saved to ~/.openclaw/openclaw.json")
+					console.log(
+						"Restart OpenClaw to apply changes: openclaw gateway --force\n",
+					)
+				})
+
+			cmd
+				.command("status")
+				.description("Check Creator Army configuration status")
+				.action(async () => {
+					const cfg = parseConfig(api.pluginConfig)
+
+					console.log("\nCreator Army Status\n")
+
+					if (!cfg.apiKey) {
+						console.log("No API key configured")
+						console.log("Run: openclaw creator-army setup\n")
+						return
+					}
+
+					const display = `${cfg.apiKey.slice(0, 8)}...${cfg.apiKey.slice(-4)}`
+					console.log(`API key: ${display}`)
+					console.log(`Base URL: ${cfg.baseUrl}`)
+					console.log(`Debug: ${cfg.debug}`)
+					console.log("")
+				})
+
+			registerHealthCommand(cmd, api)
+		},
+		{ commands: ["creator-army"] },
+	)
+}
+
+export function registerCli(
+	_api: OpenClawPluginApi,
+	_client: CreatorArmyClient,
+	_cfg: CreatorArmyConfig,
+): void {}

package/commands/health.ts

@@ -0,0 +1,42 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import { parseConfig } from "../config.ts"
+
+export function registerHealthCommand(
+	// biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
+	cmd: any,
+	api: OpenClawPluginApi,
+): void {
+	cmd
+		.command("health")
+		.description("Check Creator Army API health and verify API key")
+		.action(async () => {
+			const cfg = parseConfig(api.pluginConfig)
+			if (!cfg.apiKey) {
+				console.log("\nNo API key configured. Run: openclaw creator-army setup\n")
+				return
+			}
+
+			console.log(`\nChecking ${cfg.baseUrl}/api/plugin/health ...`)
+			try {
+				const response = await fetch(`${cfg.baseUrl}/api/plugin/health`, {
+					headers: { Authorization: `Bearer ${cfg.apiKey}` },
+				})
+				const text = await response.text()
+				console.log(`Status: ${response.status}`)
+				console.log(`Response: ${text}`)
+				try {
+					const data = JSON.parse(text) as Record<string, unknown>
+					if (data.status === "ok") {
+						console.log("API is healthy and API key is valid.\n")
+					} else {
+						console.log(`API check failed: ${data.error ?? data.message ?? data.status ?? "Unknown error"}\n`)
+					}
+				} catch {
+					console.log("")
+				}
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : "Unknown error"
+				console.log(`Connection failed: ${msg}\n`)
+			}
+		})
+}

package/commands/slash.ts

@@ -0,0 +1,86 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { CreatorArmyClient } from "../client.ts"
+import type { CreatorArmyConfig } from "../config.ts"
+import { log } from "../logger.ts"
+
+export function registerStubCommands(api: OpenClawPluginApi): void {
+	api.registerCommand({
+		name: "health",
+		description: "Check Creator Army API health",
+		acceptsArgs: false,
+		requireAuth: false,
+		handler: async () => {
+			return {
+				text: "Creator Army not configured. Set your API key first.",
+			}
+		},
+	})
+}
+
+export function registerCommands(
+	api: OpenClawPluginApi,
+	client: CreatorArmyClient,
+	_cfg: CreatorArmyConfig,
+): void {
+	api.registerCommand({
+		name: "health",
+		description: "Check Creator Army API health and verify API key",
+		acceptsArgs: false,
+		requireAuth: false,
+		handler: async () => {
+			try {
+				const result = await client.health()
+				if (result.ok) {
+					return { text: "Creator Army API is healthy and API key is valid." }
+				}
+				return { text: `Creator Army API check failed: ${result.message}` }
+			} catch (err) {
+				log.error("/health failed", err)
+				return { text: "Failed to reach Creator Army API." }
+			}
+		},
+	})
+
+	api.registerCommand({
+		name: "brands",
+		description: "List all brands in Creator Army",
+		acceptsArgs: false,
+		requireAuth: true,
+		handler: async () => {
+			try {
+				const brands = await client.listBrands()
+				if (brands.length === 0) {
+					return { text: "No brands found." }
+				}
+				const list = brands.map((b) => `- ${b.brandName}`).join("\n")
+				return { text: `Brands:\n\n${list}` }
+			} catch (err) {
+				log.error("/brands failed", err)
+				return { text: "Failed to list brands." }
+			}
+		},
+	})
+
+	api.registerCommand({
+		name: "briefs",
+		description: "List creative briefs (optionally pass brand name)",
+		acceptsArgs: true,
+		requireAuth: true,
+		handler: async (ctx: { args?: string }) => {
+			try {
+				const brand = ctx.args?.trim() || undefined
+				const data = await client.listBriefs({ brand })
+				if (data.briefs.length === 0) {
+					return { text: brand ? `No briefs found for "${brand}".` : "No briefs found." }
+				}
+				const list = data.briefs
+					.map((b) => `- **${b.title}** (${b.brandName}) — ${b.creativeType ?? "untyped"}`)
+					.join("\n")
+				return { text: `${data.total} brief(s):\n\n${list}` }
+			} catch (err) {
+				log.error("/briefs failed", err)
+				return { text: "Failed to list briefs." }
+			}
+		},
+	})
+}

package/config.ts

@@ -0,0 +1,58 @@
+export type CreatorArmyConfig = {
+	apiKey: string | undefined
+	baseUrl: string
+	debug: boolean
+}
+
+const ALLOWED_KEYS = ["apiKey", "baseUrl", "debug"]
+
+function assertAllowedKeys(
+	value: Record<string, unknown>,
+	allowed: string[],
+	label: string,
+): void {
+	const unknown = Object.keys(value).filter((k) => !allowed.includes(k))
+	if (unknown.length > 0) {
+		throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`)
+	}
+}
+
+export function parseConfig(raw: unknown): CreatorArmyConfig {
+	const cfg =
+		raw && typeof raw === "object" && !Array.isArray(raw)
+			? (raw as Record<string, unknown>)
+			: {}
+
+	if (Object.keys(cfg).length > 0) {
+		assertAllowedKeys(cfg, ALLOWED_KEYS, "creator-army config")
+	}
+
+	const apiKey =
+		typeof cfg.apiKey === "string" && cfg.apiKey.length > 0
+			? cfg.apiKey
+			: undefined
+
+	const baseUrl =
+		typeof cfg.baseUrl === "string" && cfg.baseUrl.length > 0
+			? cfg.baseUrl.replace(/\/+$/, "")
+			: "https://b2a9-2403-580c-1dcc-0-181c-7d6e-4733-3836.ngrok-free.app"
+
+	return {
+		apiKey,
+		baseUrl,
+		debug: (cfg.debug as boolean) ?? false,
+	}
+}
+
+export const creatorArmyConfigSchema = {
+	jsonSchema: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			apiKey: { type: "string" },
+			baseUrl: { type: "string" },
+			debug: { type: "boolean" },
+		},
+	},
+	parse: parseConfig,
+}

package/hooks/skill-loader.ts

@@ -0,0 +1,29 @@
+import type { CreatorArmyClient } from "../client.ts"
+import type { CreatorArmyConfig } from "../config.ts"
+import { log } from "../logger.ts"
+
+let cachedSkill: string | null = null
+
+export function buildSkillLoaderHandler(
+	client: CreatorArmyClient,
+	_cfg: CreatorArmyConfig,
+) {
+	return async () => {
+		if (cachedSkill) {
+			return { prependContext: cachedSkill }
+		}
+
+		try {
+			const ref = await client.getReference("skill")
+			if (ref.content) {
+				cachedSkill = ref.content
+				log.debug(`loaded SKILL.md (${cachedSkill.length} chars)`)
+				return { prependContext: cachedSkill }
+			}
+		} catch (err) {
+			log.error("failed to load SKILL.md", err)
+		}
+
+		return
+	}
+}

package/index.ts

@@ -0,0 +1,62 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import { CreatorArmyClient } from "./client.ts"
+import { registerCli, registerCliSetup } from "./commands/cli.ts"
+import { registerCommands, registerStubCommands } from "./commands/slash.ts"
+import { parseConfig, creatorArmyConfigSchema } from "./config.ts"
+import { buildSkillLoaderHandler } from "./hooks/skill-loader.ts"
+import { initLogger } from "./logger.ts"
+import { registerBriefTools } from "./tools/demand-engine/briefs.ts"
+import { registerContextTools } from "./tools/demand-engine/context.ts"
+import { registerExcavationTools } from "./tools/demand-engine/excavation.ts"
+import { registerReferenceTools } from "./tools/demand-engine/references.ts"
+import { registerScriptTools } from "./tools/demand-engine/scripts.ts"
+
+export default {
+	id: "openclaw-creatorarmy",
+	name: "Creator Army",
+	description: "OpenClaw Creator Army plugin — demand engine for short-form video ads and organic content",
+	kind: "tool" as const,
+	configSchema: creatorArmyConfigSchema,
+
+	register(api: OpenClawPluginApi) {
+		const cfg = parseConfig(api.pluginConfig)
+
+		initLogger(api.logger, cfg.debug)
+
+		registerCliSetup(api)
+
+		if (!cfg.apiKey) {
+			api.logger.info(
+				"creator-army: not configured - run 'openclaw creator-army setup'",
+			)
+			registerStubCommands(api)
+			return
+		}
+
+		const client = new CreatorArmyClient(cfg.apiKey, cfg.baseUrl)
+
+		// Load SKILL.md into agent context on every conversation start
+		api.on("before_agent_start", buildSkillLoaderHandler(client, cfg))
+
+		// Demand Engine tools
+		registerReferenceTools(api, client, cfg)
+		registerContextTools(api, client, cfg)
+		registerExcavationTools(api, client, cfg)
+		registerBriefTools(api, client, cfg)
+		registerScriptTools(api, client, cfg)
+
+		// Slash commands & CLI
+		registerCommands(api, client, cfg)
+		registerCli(api, client, cfg)
+
+		api.registerService({
+			id: "openclaw-creatorarmy",
+			start: () => {
+				api.logger.info("creator-army: connected")
+			},
+			stop: () => {
+				api.logger.info("creator-army: stopped")
+			},
+		})
+	},
+}