openclaw-ynabro 2.1.0 → 2.2.0

package/openclaw.plugin.json

@@ -35,6 +35,7 @@
   },
   "contracts": {
     "tools": [
+      "ynabro_onboarding_status",
       "ynabro_setup",
       "ynabro_save_default_plan",
       "ynabro_get_pending_transactions",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-ynabro",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "OpenClaw plugin that registers YNABro tools for YNAB integration",
   "type": "module",
   "main": "./src/index.ts",

package/skills/ynabro/prompts/ynabro.md

@@ -8,12 +8,29 @@ You are **YNABro**, a friendly and reliable YNAB assistant designed to help user
 
 ## Onboarding & Access
 
-Before performing any YNAB operations, check whether YNAB access has been set up:
+Before performing any YNAB operations, call `ynabro_onboarding_status` to check
+whether YNAB access is configured.
 
-1. A YNAB Personal Access Token must be available. In OpenClaw, the preferred storage location is `plugins.entries.openclaw-ynabro.config.token` in `openclaw.json` (surfaced as a sensitive field in the settings UI). The `YNAB_TOKEN` environment variable is also accepted as a fallback.
-2. A default plan must be selected and saved.
+If `ready` is `false`, walk the user through setup:
 
-If either is missing, call the `setupYnab()` tool first. This tool will guide the user through creating a token (if needed) and selecting a default plan. Do not attempt to read or modify transactions until setup is complete.
+1. **Missing token:** Share the `tokenInstructions` field from the status response.
+   The token must never be entered into the chat.
+   - **pi:** Call `ynabro_setup` — it presents a native TUI input popup where the
+     user enters the token directly. It goes straight to pi's AuthStorage and
+     never appears in the conversation.
+   - **OpenClaw:** Instruct the user to add the token to `openclaw.json` or via
+     the OpenClaw settings UI, then ask them to confirm when done.
+
+2. **Missing plan:** Call `ynabro_setup` to list available plans. Help the user
+   pick one. On OpenClaw, follow up with `ynabro_save_default_plan`.
+
+3. **After onboarding completes:** If the user's original message was a functional
+   request (e.g., "show my pending transactions"), fulfill it immediately.
+   Do not make them repeat themselves.
+
+If a tool returns `{ "error": "onboarding_required" }` during a conversation,
+treat it the same as a failed status check — initiate onboarding, then retry
+the original operation.
 
 ## Core Capabilities
 - Help users view, update, and manage all aspects of their YNAB budget, including:

package/src/index.ts

@@ -3,6 +3,7 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import type { YnabroConfigAdapter } from "ynabro";
 import {
   approveTransaction,
+  checkOnboardingStatus,
   getPendingTransactions,
   getPlanInfo,
   getRecentTransactions,
@@ -96,6 +97,9 @@ export default definePluginEntry({
           },
         });
       },
+      async hasToken(): Promise<boolean> {
+        return !!(api.pluginConfig as { token?: string } | undefined)?.token;
+      },
     };
 
     function getClient(): YnabroClient {
@@ -119,6 +123,18 @@ export default definePluginEntry({
       return planId;
     }
 
+    api.registerTool({
+      name: "ynabro_onboarding_status",
+      label: "Onboarding Status",
+      description:
+        "Check whether YNABro is fully configured. Returns ready status, any missing configuration, and token generation instructions.",
+      parameters: Type.Object({}),
+      async execute() {
+        const status = await checkOnboardingStatus(openClawAdapter);
+        return ok(JSON.stringify(status));
+      },
+    });
+
     api.registerTool({
       name: "ynabro_setup",
       label: "Setup YNAB",
@@ -150,17 +166,27 @@ export default definePluginEntry({
         "Call ynabro_setup first to get the list of available plan IDs.",
       parameters: saveDefaultPlanSchema,
       async execute(_id, raw) {
-        const p = params(raw);
-        const client = getClient();
-        const plans = await client.getPlans();
-        await setupYnab(client, plans, p.planId as string, openClawAdapter);
-        const saved = plans.find((plan) => plan.id === p.planId);
-        return ok(
-          JSON.stringify({
-            message: `Default plan set to: ${saved?.name ?? p.planId}`,
-            defaultPlanId: p.planId,
-          }),
-        );
+        try {
+          const p = params(raw);
+          const client = getClient();
+          const plans = await client.getPlans();
+          await setupYnab(client, plans, p.planId as string, openClawAdapter);
+          const saved = plans.find((plan) => plan.id === p.planId);
+          return ok(
+            JSON.stringify({
+              message: `Default plan set to: ${saved?.name ?? p.planId}`,
+              defaultPlanId: p.planId,
+            }),
+          );
+        } catch (_error) {
+          const status = await checkOnboardingStatus(openClawAdapter);
+          return ok(
+            JSON.stringify({
+              error: "onboarding_required",
+              ...status,
+            }),
+          );
+        }
       },
     });
 
@@ -170,12 +196,22 @@ export default definePluginEntry({
       description: "Get all pending (uncategorized) transactions for a plan",
       parameters: Type.Object({}),
       async execute() {
-        const [client, planId] = await Promise.all([
-          Promise.resolve(getClient()),
-          getDefaultPlanId(),
-        ]);
-        const result = await getPendingTransactions(client, planId);
-        return ok(JSON.stringify(result, null, 2));
+        try {
+          const [client, planId] = await Promise.all([
+            Promise.resolve(getClient()),
+            getDefaultPlanId(),
+          ]);
+          const result = await getPendingTransactions(client, planId);
+          return ok(JSON.stringify(result, null, 2));
+        } catch (_error) {
+          const status = await checkOnboardingStatus(openClawAdapter);
+          return ok(
+            JSON.stringify({
+              error: "onboarding_required",
+              ...status,
+            }),
+          );
+        }
       },
     });
 
@@ -185,12 +221,22 @@ export default definePluginEntry({
       description: "Get recent transactions for a plan",
       parameters: Type.Object({}),
       async execute() {
-        const [client, planId] = await Promise.all([
-          Promise.resolve(getClient()),
-          getDefaultPlanId(),
-        ]);
-        const result = await getRecentTransactions(client, planId);
-        return ok(JSON.stringify(result, null, 2));
+        try {
+          const [client, planId] = await Promise.all([
+            Promise.resolve(getClient()),
+            getDefaultPlanId(),
+          ]);
+          const result = await getRecentTransactions(client, planId);
+          return ok(JSON.stringify(result, null, 2));
+        } catch (_error) {
+          const status = await checkOnboardingStatus(openClawAdapter);
+          return ok(
+            JSON.stringify({
+              error: "onboarding_required",
+              ...status,
+            }),
+          );
+        }
       },
     });
 
@@ -200,13 +246,23 @@ export default definePluginEntry({
       description: "Approve a specific transaction",
       parameters: approveSchema,
       async execute(_id, raw) {
-        const p = params(raw);
-        const [client, planId] = await Promise.all([
-          Promise.resolve(getClient()),
-          getDefaultPlanId(),
-        ]);
-        await approveTransaction(client, planId, p.transactionId as string);
-        return ok(JSON.stringify({ success: true }));
+        try {
+          const p = params(raw);
+          const [client, planId] = await Promise.all([
+            Promise.resolve(getClient()),
+            getDefaultPlanId(),
+          ]);
+          await approveTransaction(client, planId, p.transactionId as string);
+          return ok(JSON.stringify({ success: true }));
+        } catch (_error) {
+          const status = await checkOnboardingStatus(openClawAdapter);
+          return ok(
+            JSON.stringify({
+              error: "onboarding_required",
+              ...status,
+            }),
+          );
+        }
       },
     });
 
@@ -216,12 +272,22 @@ export default definePluginEntry({
       description: "Get basic information about a plan",
       parameters: Type.Object({}),
       async execute() {
-        const [client, planId] = await Promise.all([
-          Promise.resolve(getClient()),
-          getDefaultPlanId(),
-        ]);
-        const result = await getPlanInfo(client, planId);
-        return ok(JSON.stringify(result, null, 2));
+        try {
+          const [client, planId] = await Promise.all([
+            Promise.resolve(getClient()),
+            getDefaultPlanId(),
+          ]);
+          const result = await getPlanInfo(client, planId);
+          return ok(JSON.stringify(result, null, 2));
+        } catch (_error) {
+          const status = await checkOnboardingStatus(openClawAdapter);
+          return ok(
+            JSON.stringify({
+              error: "onboarding_required",
+              ...status,
+            }),
+          );
+        }
       },
     });