@laburen/openclaw-plugin-whatsapp-api 0.6.0 → 0.7.0

package/README.md

@@ -120,6 +120,19 @@ Responses: **`403`** if the shared secret does not match, **`400`** if the paylo
 
 Per-account fields can override phone id, token, retries, etc. under `channels["whatsapp-api"].accounts.<accountId>`.
 
+## LLM Usage Forwarding (`llm_output`) (opcional)
+
+Este plugin puede reenviar el usage de tokens cuando OpenClaw emite el hook `llm_output`. Cuando está configurado, hace un `POST` a `{LABUREN_WEB_APP_URL}/api/usage` y envía `Authorization: Bearer <laburenApiKey>`.
+
+Para activarlo, configura estas keys del entry del plugin (no del channel):
+
+```bash
+openclaw config set plugins.entries.whatsapp-api.LABUREN_WEB_APP_URL "https://tu-laburen.example"
+openclaw config set plugins.entries.whatsapp-api.userPhoneNumber "+1234567890"
+openclaw config set plugins.entries.whatsapp-api.laburenApiKey "tu-api-key"
+openclaw gateway restart
+```
+
 ## Notes
 
 - Outbound mode is **direct-to-Meta** only (no third-party relay in this plugin).

package/index.js

@@ -1429,9 +1429,29 @@ const log$3 = waLogger("llm-output/forward-usage");
 /** Plugin extension config keys (see `openclaw.plugin.json`). */
 const LABUREN_WEB_APP_CONFIG_KEY = "LABUREN_WEB_APP_URL";
 const USER_PHONE_CONFIG_KEY = "userPhoneNumber";
+const LABUREN_API_KEY_CONFIG_KEY = "laburenApiKey";
 const USAGE_PATH = "/api/usage";
-const USAGE_FEATURE = "openclaw_run";
 const POST_TIMEOUT_MS = 3e3;
+/**
+* OpenClaw classifies each run by `trigger`. Only `user` (and `manual` admin
+* actions) should be billed as real product usage. Background runs initiated
+* by the runtime (`heartbeat`) or by scheduled jobs (`cron`, `memory`,
+* `overflow`) must be reported under a separate feature so the backend can
+* apply a different billing policy.
+*
+* Without this mapping every heartbeat and every duplicated wa-api cron tick
+* (which both fire every 30m) was charged to the user as `openclaw_run`,
+* draining credits without any real interaction.
+*/
+function resolveFeatureFromTrigger(trigger) {
+	switch (trigger) {
+		case "heartbeat":
+		case "cron":
+		case "memory":
+		case "overflow": return "heartbeat_run";
+		default: return "openclaw_run";
+	}
+}
 function resolveUsageIngestUrl() {
 	let baseRaw;
 	try {
@@ -1460,6 +1480,17 @@ function resolveUserPhoneNumber() {
 	const phone = raw.trim();
 	return phone.length > 0 ? phone : null;
 }
+function resolveLaburenApiKey() {
+	let raw;
+	try {
+		raw = getPluginApi().pluginConfig?.[LABUREN_API_KEY_CONFIG_KEY];
+	} catch {
+		return null;
+	}
+	if (typeof raw !== "string") return null;
+	const key = raw.trim();
+	return key.length > 0 ? key : null;
+}
 async function handleForwardLlmUsage(event, ctx) {
 	const usage = event.usage;
 	if (!usage) return;
@@ -1467,13 +1498,18 @@ async function handleForwardLlmUsage(event, ctx) {
 	if (!endpoint) return;
 	const userPhoneNumber = resolveUserPhoneNumber();
 	if (!userPhoneNumber) return;
+	const laburenApiKey = resolveLaburenApiKey();
+	if (!laburenApiKey) {
+		log$3.warn(`usage-forwarder: missing ${LABUREN_API_KEY_CONFIG_KEY} (required for authenticated /api/usage calls)`);
+		return;
+	}
 	const input = usage.input ?? 0;
 	const output = usage.output ?? 0;
 	const cacheRead = usage.cacheRead ?? 0;
 	const cacheWrite = usage.cacheWrite ?? 0;
 	const total = usage.total ?? input + output + cacheRead + cacheWrite;
 	const body = {
-		feature: USAGE_FEATURE,
+		feature: resolveFeatureFromTrigger(ctx.trigger),
 		runId: event.runId,
 		sessionId: event.sessionId,
 		userPhoneNumber,
@@ -1493,7 +1529,10 @@ async function handleForwardLlmUsage(event, ctx) {
 	try {
 		const res = await fetch(endpoint, {
 			method: "POST",
-			headers: { "Content-Type": "application/json" },
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${laburenApiKey}`
+			},
 			body: JSON.stringify(body),
 			signal: AbortSignal.timeout(POST_TIMEOUT_MS)
 		});
@@ -1662,6 +1701,12 @@ const plugin = {
 	id: "whatsapp-api",
 	name: "WhatsApp API",
 	description: "WhatsApp API channel plugin with inbound webhook and direct Meta outbound",
+	/**
+	* Called by OpenClaw when the plugin loads: publishes the channel, wires the
+	* global plugin API holder, then registers pipeline hooks and plugin services.
+	*
+	* @param api - Plugin API injected by the host (config, runtime, registration helpers)
+	*/
 	register(api) {
 		setPluginApi(api);
 		api.registerChannel({ plugin: createWhatsAppApiChannel(api) });

package/openclaw.plugin.json

@@ -17,6 +17,10 @@
         "type": "string",
         "description": "WhatsApp user phone (E.164 or your normalised form). Sent on each usage POST so the backend can resolve the user."
       },
+      "laburenApiKey": {
+        "type": "string",
+        "description": "Bearer token for the Laburen usage ingest API (sent as `Authorization: Bearer <laburenApiKey>` on POST {base}/api/usage)."
+      },
       "defaults": {
         "type": "object",
         "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laburen/openclaw-plugin-whatsapp-api",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "WhatsApp API channel plugin for OpenClaw",
   "main": "index.js",

package/src/scripts/setup.sh

@@ -3,8 +3,8 @@
 # Run once per OpenClaw instance.
 #
 # Usage:
-#   bash setup.sh             → installs the cron
-#   bash setup.sh --uninstall → removes the cron
+#   bash setup.sh             → installs the cron (cleans up duplicates first)
+#   bash setup.sh --uninstall → removes all instances of the cron
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 CHECK_SCRIPT="$SCRIPT_DIR/check.sh"
@@ -18,22 +18,45 @@ for arg in "$@"; do
   esac
 done
 
+# List all job IDs that match $JOB_NAME. Uses `awk` instead of `jq` because the
+# openclaw container image does not include jq (the previous version of this
+# script silently failed the existence check, which caused duplicate crons to
+# accumulate on every plugin boot — one debit per duplicate, per tick).
+list_existing_ids() {
+  openclaw cron list 2>/dev/null \
+    | awk -v name="$JOB_NAME" 'index($0, name) {print $1}'
+}
+
 if [ "$UNINSTALL" = "true" ]; then
-  JOB_ID=$(openclaw cron list --json 2>/dev/null | jq -r ".jobs[] | select(.name == \"$JOB_NAME\") | .id")
-  if [ -n "$JOB_ID" ]; then
-    openclaw cron rm "$JOB_ID"
-    echo "[$JOB_NAME] Cron job removed (id: $JOB_ID)."
-  else
+  REMOVED=0
+  while read -r id; do
+    [ -z "$id" ] && continue
+    if openclaw cron rm "$id" >/dev/null 2>&1; then
+      echo "[$JOB_NAME] Cron job removed (id: $id)."
+      REMOVED=$((REMOVED + 1))
+    fi
+  done < <(list_existing_ids)
+  if [ "$REMOVED" -eq 0 ]; then
     echo "[$JOB_NAME] No cron job found to remove."
   fi
   exit 0
 fi
 
-# Check if already installed
-EXISTING=$(openclaw cron list --json 2>/dev/null | jq -r ".jobs[] | select(.name == \"$JOB_NAME\") | .id")
-if [ -n "$EXISTING" ]; then
-  echo "[$JOB_NAME] Already installed (id: $EXISTING). Run with --uninstall first to reinstall."
+# Count existing instances. If zero → install. If one → idempotent skip.
+# If more than one → cleanup duplicates and reinstall one (self-heal).
+EXISTING_IDS=$(list_existing_ids)
+EXISTING_COUNT=$(printf '%s\n' "$EXISTING_IDS" | awk 'NF' | wc -l)
+
+if [ "$EXISTING_COUNT" -eq 1 ]; then
+  echo "[$JOB_NAME] Already installed (id: $EXISTING_IDS). Skipping."
   exit 0
+elif [ "$EXISTING_COUNT" -gt 1 ]; then
+  echo "[$JOB_NAME] Found $EXISTING_COUNT duplicate instance(s). Cleaning up before reinstall..."
+  while read -r id; do
+    [ -z "$id" ] && continue
+    openclaw cron rm "$id" >/dev/null 2>&1 \
+      && echo "[$JOB_NAME] Removed duplicate id: $id"
+  done < <(printf '%s\n' "$EXISTING_IDS")
 fi
 
 chmod +x "$CHECK_SCRIPT"