@creatorarmy/openclaw-creatorarmy 1.0.0

package/logger.ts

@@ -0,0 +1,54 @@
+export type LoggerBackend = {
+	info(msg: string, ...args: unknown[]): void
+	warn(msg: string, ...args: unknown[]): void
+	error(msg: string, ...args: unknown[]): void
+	debug?(msg: string, ...args: unknown[]): void
+}
+
+const NOOP_LOGGER: LoggerBackend = {
+	info() {},
+	warn() {},
+	error() {},
+	debug() {},
+}
+
+let _backend: LoggerBackend = NOOP_LOGGER
+let _debug = false
+
+export function initLogger(backend: LoggerBackend, debug: boolean): void {
+	_backend = backend
+	_debug = debug
+}
+
+export const log = {
+	info(msg: string, ...args: unknown[]): void {
+		_backend.info(`creator-army: ${msg}`, ...args)
+	},
+
+	warn(msg: string, ...args: unknown[]): void {
+		_backend.warn(`creator-army: ${msg}`, ...args)
+	},
+
+	error(msg: string, err?: unknown): void {
+		const detail = err instanceof Error ? err.message : err ? String(err) : ""
+		_backend.error(`creator-army: ${msg}${detail ? ` — ${detail}` : ""}`)
+	},
+
+	debug(msg: string, ...args: unknown[]): void {
+		if (!_debug) return
+		const fn = _backend.debug ?? _backend.info
+		fn(`creator-army [debug]: ${msg}`, ...args)
+	},
+
+	debugRequest(method: string, params: Record<string, unknown>): void {
+		if (!_debug) return
+		const fn = _backend.debug ?? _backend.info
+		fn(`creator-army [debug] → ${method}`, JSON.stringify(params, null, 2))
+	},
+
+	debugResponse(method: string, data: unknown): void {
+		if (!_debug) return
+		const fn = _backend.debug ?? _backend.info
+		fn(`creator-army [debug] ← ${method}`, JSON.stringify(data, null, 2))
+	},
+}

package/openclaw.plugin.json

@@ -0,0 +1,33 @@
+{
+	"id": "openclaw-creatorarmy",
+	"kind": "tool",
+	"uiHints": {
+		"apiKey": {
+			"label": "Creator Army API Key",
+			"sensitive": true,
+			"placeholder": "ca_...",
+			"help": "Your API key from Creator Army (or use ${CREATOR_ARMY_API_KEY})"
+		},
+		"baseUrl": {
+			"label": "API Base URL",
+			"placeholder": "https://api.creatorarmy.com",
+			"help": "Override the API base URL (or use ${CREATOR_ARMY_BASE_URL})",
+			"advanced": true
+		},
+		"debug": {
+			"label": "Debug Logging",
+			"help": "Enable verbose debug logs for API calls and responses",
+			"advanced": true
+		}
+	},
+	"configSchema": {
+		"type": "object",
+		"additionalProperties": false,
+		"properties": {
+			"apiKey": { "type": "string" },
+			"baseUrl": { "type": "string" },
+			"debug": { "type": "boolean" }
+		},
+		"required": []
+	}
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "@creatorarmy/openclaw-creatorarmy",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "OpenClaw Creator Army plugin",
+	"license": "MIT",
+	"dependencies": {
+		"@sinclair/typebox": "0.34.47"
+	},
+	"scripts": {
+		"check-types": "tsc --noEmit",
+		"lint": "bunx @biomejs/biome ci .",
+		"lint:fix": "bunx @biomejs/biome check --write ."
+	},
+	"peerDependencies": {
+		"openclaw": ">=2026.1.29"
+	},
+	"openclaw": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"devDependencies": {
+		"typescript": "^5.9.3"
+	}
+}

package/tools/demand-engine/briefs.ts

@@ -0,0 +1,110 @@
+import { Type } from "@sinclair/typebox"
+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 registerBriefTools(
+	api: OpenClawPluginApi,
+	client: CreatorArmyClient,
+	_cfg: CreatorArmyConfig,
+): void {
+	api.registerTool(
+		{
+			name: "demand_engine_list_briefs",
+			label: "List Creative Briefs",
+			description:
+				"List creative briefs. Optionally filter by brand name. Briefs contain the selling sequence, hooks, building blocks, and creative type for an ad concept.",
+			parameters: Type.Object({
+				brand: Type.Optional(Type.String({ description: "Filter by brand name" })),
+				limit: Type.Optional(Type.Number({ description: "Max results (default 20)" })),
+				offset: Type.Optional(Type.Number({ description: "Pagination offset" })),
+			}),
+			async execute(
+				_id: string,
+				params: { brand?: string; limit?: number; offset?: number },
+			) {
+				log.debug(`listing briefs: brand=${params.brand ?? "all"}`)
+				const data = await client.listBriefs(params)
+				if (data.briefs.length === 0) {
+					return {
+						content: [{ type: "text" as const, text: "No briefs found." }],
+						details: {},
+					}
+				}
+				const list = data.briefs
+					.map((b) => `- **${b.title}** (${b.brandName}) — ${b.creativeType ?? "untyped"}, ${b.customerType ?? "general"}`)
+					.join("\n")
+				return {
+					content: [{ type: "text" as const, text: `${data.total} brief(s):\n\n${list}` }],
+					details: { total: data.total },
+				}
+			},
+		},
+		{ name: "demand_engine_list_briefs" },
+	)
+
+	api.registerTool(
+		{
+			name: "demand_engine_get_brief",
+			label: "Get Creative Brief",
+			description: "Get a single creative brief by ID with full selling sequence and hooks.",
+			parameters: Type.Object({
+				id: Type.String({ description: "Brief ID" }),
+			}),
+			async execute(_id: string, params: { id: string }) {
+				log.debug(`getting brief: ${params.id}`)
+				const brief = await client.getBrief(params.id)
+				if (!brief) {
+					return {
+						content: [{ type: "text" as const, text: "Brief not found." }],
+						details: {},
+					}
+				}
+				return {
+					content: [{ type: "text" as const, text: JSON.stringify(brief, null, 2) }],
+					details: { id: brief._id, title: brief.title },
+				}
+			},
+		},
+		{ name: "demand_engine_get_brief" },
+	)
+
+	api.registerTool(
+		{
+			name: "demand_engine_save_brief",
+			label: "Save Creative Brief",
+			description:
+				"Save a new creative brief with selling sequence, hooks, building blocks, and creative type. This is Steps 2-3 of the demand engine.",
+			parameters: Type.Object({
+				brandName: Type.String({ description: "Brand name" }),
+				title: Type.String({ description: "Brief title" }),
+				customerType: Type.Optional(Type.String({ description: "Target customer type" })),
+				sellingSequence: Type.Optional(
+					Type.Object({
+						rapport: Type.Optional(Type.String()),
+						openLoop: Type.Optional(Type.String()),
+						valueStack: Type.Optional(Type.String()),
+						wowMoment: Type.Optional(Type.String()),
+						cta: Type.Optional(Type.String()),
+					}),
+				),
+				hooks: Type.Optional(Type.Array(Type.String(), { description: "Hook options" })),
+				buildingBlocks: Type.Optional(Type.Array(Type.String(), { description: "Persuasion building blocks used" })),
+				creativeType: Type.Optional(Type.String({ description: "Ad format (e.g. founder-to-camera, ugc, mashup)" })),
+				platform: Type.Optional(Type.String({ description: "Target platform (e.g. meta, tiktok)" })),
+				duration: Type.Optional(Type.Number({ description: "Target duration in seconds" })),
+				notes: Type.Optional(Type.String({ description: "Production or strategy notes" })),
+			}),
+			async execute(_id: string, params: Record<string, unknown>) {
+				log.debug(`saving brief: ${params.title}`)
+				const brief = await client.saveBrief(params)
+				return {
+					content: [{ type: "text" as const, text: `Saved brief "${brief.title}" for ${brief.brandName}.` }],
+					details: { id: brief._id, title: brief.title },
+				}
+			},
+		},
+		{ name: "demand_engine_save_brief" },
+	)
+}

package/tools/demand-engine/context.ts

@@ -0,0 +1,93 @@
+import { Type } from "@sinclair/typebox"
+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 registerContextTools(
+	api: OpenClawPluginApi,
+	client: CreatorArmyClient,
+	_cfg: CreatorArmyConfig,
+): void {
+	api.registerTool(
+		{
+			name: "demand_engine_list_brands",
+			label: "List Brands",
+			description: "List all brands with saved context in Creator Army.",
+			parameters: Type.Object({}),
+			async execute() {
+				log.debug("listing brands")
+				const brands = await client.listBrands()
+				if (brands.length === 0) {
+					return {
+						content: [{ type: "text" as const, text: "No brands found. Use demand_engine_save_context to create one." }],
+						details: {},
+					}
+				}
+				const list = brands.map((b) => `- ${b.brandName}${b.brandUrl ? ` (${b.brandUrl})` : ""}`).join("\n")
+				return {
+					content: [{ type: "text" as const, text: `Brands:\n\n${list}` }],
+					details: { count: brands.length },
+				}
+			},
+		},
+		{ name: "demand_engine_list_brands" },
+	)
+
+	api.registerTool(
+		{
+			name: "demand_engine_get_context",
+			label: "Get Brand Context",
+			description:
+				"Get full brand context for a specific brand — personality, tone, visual style, ICP, customer types, barriers, motivators. This is Step 0 of the demand engine.",
+			parameters: Type.Object({
+				brand: Type.String({ description: "Brand name (case-insensitive)" }),
+			}),
+			async execute(_id: string, params: { brand: string }) {
+				log.debug(`getting context for: ${params.brand}`)
+				const ctx = await client.getBrandContext(params.brand)
+				if (!ctx) {
+					return {
+						content: [{ type: "text" as const, text: `No context found for "${params.brand}". Run customer excavation to build it.` }],
+						details: {},
+					}
+				}
+				return {
+					content: [{ type: "text" as const, text: JSON.stringify(ctx, null, 2) }],
+					details: { brandName: ctx.brandName },
+				}
+			},
+		},
+		{ name: "demand_engine_get_context" },
+	)
+
+	api.registerTool(
+		{
+			name: "demand_engine_save_context",
+			label: "Save Brand Context",
+			description:
+				"Create or update brand context (upserts by brandName). Save personality, tone, visual style, ICP, customer types, barriers, and motivators.",
+			parameters: Type.Object({
+				brandName: Type.String({ description: "Brand name" }),
+				brandUrl: Type.Optional(Type.String({ description: "Brand website URL" })),
+				personality: Type.Optional(Type.String({ description: "Brand personality" })),
+				tone: Type.Optional(Type.String({ description: "Brand tone of voice" })),
+				visualStyle: Type.Optional(Type.String({ description: "Visual style for content" })),
+				icp: Type.Optional(Type.String({ description: "Ideal customer profile" })),
+				customerTypes: Type.Optional(Type.Array(Type.String(), { description: "Customer type names" })),
+				barriers: Type.Optional(Type.Array(Type.String(), { description: "Purchase barriers" })),
+				motivators: Type.Optional(Type.Array(Type.String(), { description: "Purchase motivators" })),
+				notes: Type.Optional(Type.String({ description: "Additional notes" })),
+			}),
+			async execute(_id: string, params: Record<string, unknown>) {
+				log.debug(`saving context for: ${params.brandName}`)
+				const ctx = await client.saveBrandContext(params)
+				return {
+					content: [{ type: "text" as const, text: `Saved brand context for "${ctx.brandName}".` }],
+					details: { brandName: ctx.brandName },
+				}
+			},
+		},
+		{ name: "demand_engine_save_context" },
+	)
+}

package/tools/demand-engine/excavation.ts

@@ -0,0 +1,74 @@
+import { Type } from "@sinclair/typebox"
+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 registerExcavationTools(
+	api: OpenClawPluginApi,
+	client: CreatorArmyClient,
+	_cfg: CreatorArmyConfig,
+): void {
+	api.registerTool(
+		{
+			name: "demand_engine_get_excavation",
+			label: "Get Customer Excavation",
+			description:
+				"Get customer excavation data for a brand — customer types with their barriers and motivators, core problem, failed solutions, desired outcome, and unique mechanism. This is Step 1 of the demand engine.",
+			parameters: Type.Object({
+				brand: Type.String({ description: "Brand name" }),
+			}),
+			async execute(_id: string, params: { brand: string }) {
+				log.debug(`getting excavation for: ${params.brand}`)
+				const exc = await client.getExcavation(params.brand)
+				if (!exc) {
+					return {
+						content: [{ type: "text" as const, text: `No excavation found for "${params.brand}". Use demand_engine_save_excavation to create one.` }],
+						details: {},
+					}
+				}
+				return {
+					content: [{ type: "text" as const, text: JSON.stringify(exc, null, 2) }],
+					details: { brandName: exc.brandName },
+				}
+			},
+		},
+		{ name: "demand_engine_get_excavation" },
+	)
+
+	api.registerTool(
+		{
+			name: "demand_engine_save_excavation",
+			label: "Save Customer Excavation",
+			description:
+				"Create or update customer excavation data (upserts by brandName). Save customer types with barriers/motivators, core problem, failed solutions, desired outcome, and unique mechanism.",
+			parameters: Type.Object({
+				brandName: Type.String({ description: "Brand name" }),
+				customerTypes: Type.Optional(
+					Type.Array(
+						Type.Object({
+							name: Type.String({ description: "Customer type name" }),
+							description: Type.Optional(Type.String({ description: "Description of this customer type" })),
+							barriers: Type.Optional(Type.Array(Type.String(), { description: "Their purchase barriers" })),
+							motivators: Type.Optional(Type.Array(Type.String(), { description: "What motivates them to buy" })),
+						}),
+					),
+				),
+				coreProblem: Type.Optional(Type.String({ description: "The core problem customers face" })),
+				failedSolutions: Type.Optional(Type.String({ description: "What they tried that didn't work" })),
+				desiredOutcome: Type.Optional(Type.String({ description: "What they want to achieve" })),
+				uniqueMechanism: Type.Optional(Type.String({ description: "Why this product works when others didn't" })),
+				notes: Type.Optional(Type.String({ description: "Additional notes" })),
+			}),
+			async execute(_id: string, params: Record<string, unknown>) {
+				log.debug(`saving excavation for: ${params.brandName}`)
+				const exc = await client.saveExcavation(params)
+				return {
+					content: [{ type: "text" as const, text: `Saved excavation for "${exc.brandName}".` }],
+					details: { brandName: exc.brandName },
+				}
+			},
+		},
+		{ name: "demand_engine_save_excavation" },
+	)
+}

package/tools/demand-engine/references.ts

@@ -0,0 +1,55 @@
+import { Type } from "@sinclair/typebox"
+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 registerReferenceTools(
+	api: OpenClawPluginApi,
+	client: CreatorArmyClient,
+	_cfg: CreatorArmyConfig,
+): void {
+	api.registerTool(
+		{
+			name: "demand_engine_list_references",
+			label: "List Reference Docs",
+			description:
+				"List all available Creator Army demand engine reference documents (hook science, selling sequence, creative types, etc).",
+			parameters: Type.Object({}),
+			async execute() {
+				log.debug("listing references")
+				const refs = await client.listReferences()
+				const list = refs.map((r) => `- ${r.slug} (${r.filename})`).join("\n")
+				return {
+					content: [{ type: "text" as const, text: `Available references:\n\n${list}` }],
+					details: { count: refs.length },
+				}
+			},
+		},
+		{ name: "demand_engine_list_references" },
+	)
+
+	api.registerTool(
+		{
+			name: "demand_engine_get_reference",
+			label: "Get Reference Doc",
+			description:
+				"Fetch a specific Creator Army demand engine reference document by slug. Use demand_engine_list_references to see available slugs. Contains frameworks for hooks, selling sequences, creative types, campaign architecture, and more.",
+			parameters: Type.Object({
+				slug: Type.String({
+					description:
+						"Reference slug (e.g. hook-science, selling-sequence, creative-types, customer-excavation, context-scan, building-blocks, lo-fi-production, campaign-architecture, learning-loop, case-studies)",
+				}),
+			}),
+			async execute(_id: string, params: { slug: string }) {
+				log.debug(`fetching reference: ${params.slug}`)
+				const ref = await client.getReference(params.slug)
+				return {
+					content: [{ type: "text" as const, text: ref.content ?? "No content found." }],
+					details: { slug: ref.slug, filename: ref.filename },
+				}
+			},
+		},
+		{ name: "demand_engine_get_reference" },
+	)
+}

package/tools/demand-engine/scripts.ts

@@ -0,0 +1,124 @@
+import { Type } from "@sinclair/typebox"
+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 registerScriptTools(
+	api: OpenClawPluginApi,
+	client: CreatorArmyClient,
+	_cfg: CreatorArmyConfig,
+): void {
+	api.registerTool(
+		{
+			name: "demand_engine_list_scripts",
+			label: "List Scripts",
+			description:
+				"List generated ad scripts. Optionally filter by brand or brief ID.",
+			parameters: Type.Object({
+				brand: Type.Optional(Type.String({ description: "Filter by brand name" })),
+				briefId: Type.Optional(Type.String({ description: "Filter by parent brief ID" })),
+				limit: Type.Optional(Type.Number({ description: "Max results (default 20)" })),
+				offset: Type.Optional(Type.Number({ description: "Pagination offset" })),
+			}),
+			async execute(
+				_id: string,
+				params: { brand?: string; briefId?: string; limit?: number; offset?: number },
+			) {
+				log.debug(`listing scripts: brand=${params.brand ?? "all"}`)
+				const data = await client.listScripts(params)
+				if (data.scripts.length === 0) {
+					return {
+						content: [{ type: "text" as const, text: "No scripts found." }],
+						details: {},
+					}
+				}
+				const list = data.scripts
+					.map((s) => `- **${s.title}** (${s.brandName}) — ${s.format ?? "untyped"}, ${s.duration ?? "?"}s`)
+					.join("\n")
+				return {
+					content: [{ type: "text" as const, text: `${data.total} script(s):\n\n${list}` }],
+					details: { total: data.total },
+				}
+			},
+		},
+		{ name: "demand_engine_list_scripts" },
+	)
+
+	api.registerTool(
+		{
+			name: "demand_engine_get_script",
+			label: "Get Script",
+			description: "Get a single ad script by ID with full body, selling sequence, and persuasion checklist.",
+			parameters: Type.Object({
+				id: Type.String({ description: "Script ID" }),
+			}),
+			async execute(_id: string, params: { id: string }) {
+				log.debug(`getting script: ${params.id}`)
+				const script = await client.getScript(params.id)
+				if (!script) {
+					return {
+						content: [{ type: "text" as const, text: "Script not found." }],
+						details: {},
+					}
+				}
+				return {
+					content: [{ type: "text" as const, text: JSON.stringify(script, null, 2) }],
+					details: { id: script._id, title: script.title },
+				}
+			},
+		},
+		{ name: "demand_engine_get_script" },
+	)
+
+	api.registerTool(
+		{
+			name: "demand_engine_save_script",
+			label: "Save Script",
+			description:
+				"Save a generated ad script with hook, open loop, body, CTA, selling sequence, building blocks, and persuasion checklist. This is Steps 3-4 of the demand engine.",
+			parameters: Type.Object({
+				brandName: Type.String({ description: "Brand name" }),
+				title: Type.String({ description: "Script title" }),
+				briefId: Type.Optional(Type.String({ description: "Parent brief ID" })),
+				customerType: Type.Optional(Type.String({ description: "Target customer type" })),
+				format: Type.Optional(Type.String({ description: "Ad format (e.g. founder-to-camera, ugc)" })),
+				platform: Type.Optional(Type.String({ description: "Target platform" })),
+				duration: Type.Optional(Type.Number({ description: "Duration in seconds" })),
+				hook: Type.Optional(Type.String({ description: "The hook (first 3 seconds)" })),
+				openLoop: Type.Optional(Type.String({ description: "The open loop (seconds 3-10)" })),
+				body: Type.Optional(Type.String({ description: "Full script body with timestamps and directions" })),
+				cta: Type.Optional(Type.String({ description: "Call to action" })),
+				sellingSequence: Type.Optional(
+					Type.Object({
+						rapport: Type.Optional(Type.String()),
+						openLoop: Type.Optional(Type.String()),
+						valueStack: Type.Optional(Type.String()),
+						wowMoment: Type.Optional(Type.String()),
+						cta: Type.Optional(Type.String()),
+					}),
+				),
+				buildingBlocks: Type.Optional(Type.Array(Type.String(), { description: "Persuasion building blocks used" })),
+				persuasionChecklist: Type.Optional(
+					Type.Object({
+						ethos: Type.Optional(Type.Boolean({ description: "Credibility/trust signal present" })),
+						logos: Type.Optional(Type.Boolean({ description: "Data or demonstration present" })),
+						pathos: Type.Optional(Type.Boolean({ description: "Makes viewer feel something" })),
+						metaphor: Type.Optional(Type.Boolean({ description: "Concept is tangible/clear" })),
+						brevity: Type.Optional(Type.Boolean({ description: "Can cut 30% and lose nothing" })),
+					}),
+				),
+				notes: Type.Optional(Type.String({ description: "Production notes" })),
+			}),
+			async execute(_id: string, params: Record<string, unknown>) {
+				log.debug(`saving script: ${params.title}`)
+				const script = await client.saveScript(params)
+				return {
+					content: [{ type: "text" as const, text: `Saved script "${script.title}" for ${script.brandName}.` }],
+					details: { id: script._id, title: script.title },
+				}
+			},
+		},
+		{ name: "demand_engine_save_script" },
+	)
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ES2022",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"allowImportingTsExtensions": true,
+		"noEmit": true,
+		"rootDir": "."
+	},
+	"include": [
+		"*.ts",
+		"tools/**/*.ts",
+		"hooks/*.ts",
+		"commands/*.ts"
+	],
+	"exclude": ["node_modules", "dist"]
+}