openclaw-ynabro 2.0.0 → 2.2.0

package/README.md

@@ -19,6 +19,7 @@ openclaw plugins install openclaw-ynabro
 ## Available Tools
 
 - `ynabro_setup`
+- `ynabro_save_default_plan`
 - `ynabro_get_pending_transactions`
 - `ynabro_get_recent_transactions`
 - `ynabro_approve_transaction`
@@ -26,6 +27,34 @@ openclaw plugins install openclaw-ynabro
 - `ynabro_get_skill_state`
 - `ynabro_update_skill_state`
 
-## Requirements
+## Configuration
+
+Set your YNAB Personal Access Token in `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-ynabro": {
+        "config": {
+          "token": "your-ynab-personal-access-token"
+        }
+      }
+    }
+  }
+}
+```
+
+OpenClaw also surfaces this as a sensitive field in its settings UI (labeled "YNAB Personal Access Token"). Generate a token at https://app.ynab.com/settings/developer.
+
+No environment variable fallback is supported.
+
+## Onboarding
+
+Run `ynabro_setup` to fetch your available YNAB plans, then `ynabro_save_default_plan` with the plan ID you want to use as the default:
+
+1. `ynabro_setup` — returns `{ plans: [{ id, name }] }`
+2. User (or agent) selects a plan from the list
+3. `ynabro_save_default_plan` with `{ planId: "<selected-id>" }` — persists the default
 
-- `YNAB_TOKEN` environment variable must be set
+After onboarding, all plan-dependent tools (`ynabro_get_pending_transactions`, `ynabro_get_recent_transactions`, `ynabro_approve_transaction`, `ynabro_get_plan_info`) resolve the plan automatically — no `planId` parameter required.

package/openclaw.plugin.json

@@ -5,6 +5,45 @@
   "skills": ["skills"],
   "configSchema": {
     "type": "object",
-    "additionalProperties": false
+    "additionalProperties": false,
+    "properties": {
+      "token": {
+        "type": "string",
+        "description": "YNAB Personal Access Token"
+      },
+      "defaultPlanId": {
+        "type": "string",
+        "description": "Default YNAB plan ID selected during onboarding"
+      }
+    }
+  },
+  "uiHints": {
+    "token": {
+      "label": "YNAB Personal Access Token",
+      "placeholder": "your-ynab-personal-access-token",
+      "sensitive": true,
+      "help": "Generate at https://app.ynab.com/settings/developer. Falls back to YNAB_TOKEN env var if not set here."
+    }
+  },
+  "setup": {
+    "providers": [
+      {
+        "id": "ynab",
+        "envVars": ["YNAB_TOKEN"]
+      }
+    ]
+  },
+  "contracts": {
+    "tools": [
+      "ynabro_onboarding_status",
+      "ynabro_setup",
+      "ynabro_save_default_plan",
+      "ynabro_get_pending_transactions",
+      "ynabro_get_recent_transactions",
+      "ynabro_approve_transaction",
+      "ynabro_get_plan_info",
+      "ynabro_get_skill_state",
+      "ynabro_update_skill_state"
+    ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-ynabro",
-  "version": "2.0.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 (via `YNAB_TOKEN` environment variable or stored in `.ynabro/config.json`).
-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

@@ -1,7 +1,9 @@
 import { Type } from "@sinclair/typebox";
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import type { YnabroConfigAdapter } from "ynabro";
 import {
   approveTransaction,
+  checkOnboardingStatus,
   getPendingTransactions,
   getPlanInfo,
   getRecentTransactions,
@@ -11,12 +13,6 @@ import {
   YnabroClient,
 } from "ynabro";
 
-function getClient(): YnabroClient {
-  const token = process.env.YNAB_TOKEN;
-  if (!token) throw new Error("YNAB_TOKEN environment variable is not set");
-  return new YnabroClient(token);
-}
-
 function params(raw: unknown): Record<string, unknown> {
   return raw as Record<string, unknown>;
 }
@@ -28,17 +24,18 @@ function ok(text: string) {
   };
 }
 
-const planIdSchema = Type.Object({
-  planId: Type.String({ description: "The ID of the YNAB plan" }),
-});
-
 const approveSchema = Type.Object({
-  planId: Type.String({ description: "The ID of the YNAB plan" }),
   transactionId: Type.String({
     description: "The ID of the transaction to approve",
   }),
 });
 
+const saveDefaultPlanSchema = Type.Object({
+  planId: Type.String({
+    description: "The ID of the YNAB plan to set as the default",
+  }),
+});
+
 const skillStateSchema = Type.Object({
   skillSlug: Type.String({
     description: "The slug identifier for the skill",
@@ -64,15 +61,132 @@ export default definePluginEntry({
   name: "YNABro",
   description: "YNAB budget management tools for OpenClaw agents",
   register(api) {
+    let cachedPlanId: string | undefined;
+
+    const openClawAdapter: YnabroConfigAdapter = {
+      async getDefaultPlanId(): Promise<string | undefined> {
+        if (cachedPlanId !== undefined) return cachedPlanId;
+        return (api.pluginConfig as { defaultPlanId?: string } | undefined)
+          ?.defaultPlanId;
+      },
+      async setDefaultPlanId(planId: string): Promise<void> {
+        cachedPlanId = planId;
+        await api.runtime.config.mutateConfigFile({
+          afterWrite: { mode: "auto" },
+          mutate: (draft) => {
+            // Ensure the path exists before writing
+            if (!draft.plugins) {
+              (draft as { plugins?: unknown }).plugins = {
+                entries: {},
+              } as unknown;
+            }
+            // TypeScript flow analysis requires explicit check after conditional assignment
+            if (draft.plugins) {
+              if (!draft.plugins.entries) {
+                draft.plugins.entries = {};
+              }
+              const existing = draft.plugins.entries["openclaw-ynabro"] ?? {};
+              const existingConfig =
+                (existing.config as Record<string, unknown> | undefined) ?? {};
+              existingConfig.defaultPlanId = planId;
+              draft.plugins.entries["openclaw-ynabro"] = {
+                ...existing,
+                config: existingConfig,
+              };
+            }
+          },
+        });
+      },
+      async hasToken(): Promise<boolean> {
+        return !!(api.pluginConfig as { token?: string } | undefined)?.token;
+      },
+    };
+
+    function getClient(): YnabroClient {
+      const token = (api.pluginConfig as { token?: string } | undefined)?.token;
+      if (!token) {
+        throw new Error(
+          "YNAB token not configured. " +
+            "Set it via plugins.entries.openclaw-ynabro.config.token in openclaw.json.",
+        );
+      }
+      return new YnabroClient(token);
+    }
+
+    async function getDefaultPlanId(): Promise<string> {
+      const planId = await openClawAdapter.getDefaultPlanId();
+      if (!planId) {
+        throw new Error(
+          "No default plan configured. Run ynabro_setup then ynabro_save_default_plan to complete onboarding.",
+        );
+      }
+      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",
       description:
-        "Set up YNAB integration — checks for token and selects a default plan",
+        "Fetch available YNAB plans for onboarding. Returns a list of plans. " +
+        "After the user selects one, call ynabro_save_default_plan with the chosen plan ID.",
       parameters: Type.Object({}),
       async execute() {
-        const result = await setupYnab();
-        return ok(JSON.stringify(result, null, 2));
+        const client = getClient();
+        const plans = await client.getPlans();
+        if (plans.length === 0) {
+          return ok(
+            JSON.stringify({ error: "No plans found in your YNAB account." }),
+          );
+        }
+        return ok(
+          JSON.stringify({
+            plans: plans.map((p) => ({ id: p.id, name: p.name })),
+          }),
+        );
+      },
+    });
+
+    api.registerTool({
+      name: "ynabro_save_default_plan",
+      label: "Save Default Plan",
+      description:
+        "Save a YNAB plan as the default for all subsequent tool calls. " +
+        "Call ynabro_setup first to get the list of available plan IDs.",
+      parameters: saveDefaultPlanSchema,
+      async execute(_id, raw) {
+        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,
+            }),
+          );
+        }
       },
     });
 
@@ -80,14 +194,24 @@ export default definePluginEntry({
       name: "ynabro_get_pending_transactions",
       label: "Get Pending Transactions",
       description: "Get all pending (uncategorized) transactions for a plan",
-      parameters: planIdSchema,
-      async execute(_id, raw) {
-        const p = params(raw);
-        const result = await getPendingTransactions(
-          getClient(),
-          p.planId as string,
-        );
-        return ok(JSON.stringify(result, null, 2));
+      parameters: Type.Object({}),
+      async execute() {
+        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,
+            }),
+          );
+        }
       },
     });
 
@@ -95,14 +219,24 @@ export default definePluginEntry({
       name: "ynabro_get_recent_transactions",
       label: "Get Recent Transactions",
       description: "Get recent transactions for a plan",
-      parameters: planIdSchema,
-      async execute(_id, raw) {
-        const p = params(raw);
-        const result = await getRecentTransactions(
-          getClient(),
-          p.planId as string,
-        );
-        return ok(JSON.stringify(result, null, 2));
+      parameters: Type.Object({}),
+      async execute() {
+        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,
+            }),
+          );
+        }
       },
     });
 
@@ -112,13 +246,23 @@ export default definePluginEntry({
       description: "Approve a specific transaction",
       parameters: approveSchema,
       async execute(_id, raw) {
-        const p = params(raw);
-        await approveTransaction(
-          getClient(),
-          p.planId as string,
-          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,
+            }),
+          );
+        }
       },
     });
 
@@ -126,11 +270,24 @@ export default definePluginEntry({
       name: "ynabro_get_plan_info",
       label: "Get Plan Info",
       description: "Get basic information about a plan",
-      parameters: planIdSchema,
-      async execute(_id, raw) {
-        const p = params(raw);
-        const result = await getPlanInfo(getClient(), p.planId as string);
-        return ok(JSON.stringify(result, null, 2));
+      parameters: Type.Object({}),
+      async execute() {
+        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,
+            }),
+          );
+        }
       },
     });