@akilles/soundcloud-watcher 2.0.4 → 2.1.0

package/README.md

@@ -2,214 +2,163 @@
 
 Monitor your SoundCloud account and track artist releases. Get notified when someone follows you, likes your tracks, or when artists you care about drop new music.
 
-
 ## Features
 
 - **Follower tracking** - See who followed you recently
 - **Track engagement** - Monitor who liked your tracks
 - **New releases** - Get notifications when tracked artists release new music
-- **Smart API usage** - Only fetches what changed, automatically skips dormant artists (configurable threshold)
+- **Smart API usage** - Only fetches what changed, automatically skips dormant artists
 - **Rate limit handling** - Exponential backoff for API reliability
-- **Automatic background checking** - Configurable interval (default: 6 hours)
-- **Session-agnostic notifications** - Works with any OpenClaw session (Telegram, Discord, etc.)
 
 ## Prerequisites
 
 - OpenClaw gateway running
 - Node.js 22+ installed
-- SoundCloud API credentials ([get them here](https://soundcloud.com/you/apps))
+- SoundCloud API credentials
 
 ## Quick Start
 
 ### 1. Install
 
 ```bash
-# From npm (recommended)
 openclaw plugins install @akilles/soundcloud-watcher
-
-# Or from source
-git clone https://github.com/wlinds/openclaw-soundcloud-watcher
-openclaw plugins install -l ./openclaw-soundcloud-watcher/openclaw-soundcloud-watcher
+openclaw plugins enable soundcloud-watcher
+openclaw gateway restart
 ```
 
-
 ### 2. Get SoundCloud Credentials
 
 1. Log into SoundCloud
 2. Go to [soundcloud.com/you/apps](https://soundcloud.com/you/apps)
 3. Click "Register a new application"
-4. Fill in name and website
-5. Copy your **Client ID** and **Client Secret** for next step
+4. Fill in name and website (any URL works)
+5. Copy your **Client ID** and **Client Secret**
 
 ### 3. Configure
 
-Run the setup command to see the configuration template:
+Create the credentials file:
 
 ```bash
-/soundcloud-setup
-```
-
-Then edit `~/.openclaw/openclaw.json` and paste your credentials:
-
-```json
-{
-  "plugins": {
-    "enabled": true,
-    "entries": {
-      "soundcloud-watcher": {
-        "enabled": true,
-        "config": {
-          "clientId": "YOUR_CLIENT_ID",
-          "clientSecret": "YOUR_CLIENT_SECRET",
-          "username": "your_soundcloud_username",
-          "checkIntervalHours": 6,
-          "myTracksLimit": 10,
-          "dormantDays": 90,
-          "sessionKey": "agent:main:main"
-        }
-      }
-    }
-  }
-}
+nano ~/.openclaw/secrets/soundcloud.env
 ```
 
-### 4. Restart & Verify
+Add your credentials:
 
-```bash
-openclaw gateway restart
-openclaw plugins list        # Should show soundcloud-watcher
-/soundcloud-status           # Should show your account info
 ```
+SOUNDCLOUD_CLIENT_ID=your_client_id
+SOUNDCLOUD_CLIENT_SECRET=your_client_secret
+MY_USERNAME=your_soundcloud_username
 
-### 5. Start Tracking your favorite artist
+# Optional settings
+INCLUDE_LINKS=true   # Include URLs in notifications (default: true)
+```
+
+### 4. Restart & Verify
 
 ```bash
-/soundcloud-add lindstedt
-/soundcloud-add noisia
-/soundcloud-list
+openclaw gateway restart
 ```
 
-Done! Updates arrive automatically every 6 hours.
+Then in chat:
+```
+/soundcloud-setup    # Should show "Already configured!"
+/soundcloud-status   # Should show your account info
+```
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `/soundcloud-setup` | Interactive setup guide with config status |
+| `/soundcloud-setup` | Show setup instructions and config status |
 | `/soundcloud-status` | Show tracking status and account info |
-| `/soundcloud-check` | Run immediate check (don't wait for interval) |
+| `/soundcloud-check` | Run immediate check (verbose output) |
+| `/soundcloud-cron` | Run check for automation (silent if no updates) |
 | `/soundcloud-add <username>` | Track artist(s) - space-separated |
-| `/soundcloud-remove <username>` | Untrack artist |
+| `/soundcloud-remove <username>` | Stop tracking an artist |
 | `/soundcloud-list` | List all tracked artists |
 
-## Configuration Options
-
-All options in `~/.openclaw/openclaw.json` under `plugins.entries.soundcloud-watcher.config`:
-
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `enabled` | boolean | No | true | Enable/disable watcher |
-| `clientId` | string | Yes | - | SoundCloud API Client ID |
-| `clientSecret` | string | Yes | - | SoundCloud API Client Secret |
-| `username` | string | Yes | - | Your SoundCloud username |
-| `checkIntervalHours` | number | No | 6 | Hours between automatic checks |
-| `myTracksLimit` | number | No | 10 | Number of your tracks to monitor |
-| `dormantDays` | number | No | 90 | Days before artist is considered dormant |
-| `sessionKey` | string | No | `agent:main:main` | OpenClaw session for notifications |
+## Automated Checking
 
-## Architecture
+The plugin responds to commands but doesn't auto-poll. Set up a cron job for automatic notifications:
 
-The plugin consists of three main components:
+```bash
+openclaw cron add --name "soundcloud-check" \
+  --every 6h \
+  --isolated \
+  --message "Run /soundcloud-cron and forward any updates to me on Telegram."
+```
 
-- **Plugin entry** ([openclaw-soundcloud-watcher/index.ts](openclaw-soundcloud-watcher/index.ts)) - Manages lifecycle, spawns watcher process
-- **Watcher** ([openclaw-soundcloud-watcher/soundcloud_watcher.ts](openclaw-soundcloud-watcher/soundcloud_watcher.ts)) - Pure TypeScript implementation of monitoring logic
-- **Manifest** ([openclaw-soundcloud-watcher/openclaw.plugin.json](openclaw-soundcloud-watcher/openclaw.plugin.json)) - Configuration schema and plugin metadata
+Uses `/soundcloud-cron` which:
+- Returns updates only (silent if nothing new)
+- Logs errors but doesn't spam on config issues
 
-### File Locations
+**Alternative:** Add to your `HEARTBEAT.md`:
+```markdown
+- [ ] Run /soundcloud-cron if not checked in last 6 hours
+```
 
-After installation:
+## File Locations
 
-- **Plugin code:** `~/.openclaw/extensions/soundcloud-watcher/`
-- **Config:** `~/.openclaw/openclaw.json`
-- **Credentials:** `~/.openclaw/secrets/soundcloud.env`
-- **Account data:** `~/.openclaw/data/soundcloud_tracking.json`
-- **Artist data:** `~/.openclaw/data/artists.json`
-- **Backoff state:** `~/.openclaw/soundcloud_backoff.json`
+| File | Purpose |
+|------|---------|
+| `~/.openclaw/secrets/soundcloud.env` | Your API credentials |
+| `~/.openclaw/data/artists.json` | Tracked artists data |
+| `~/.openclaw/data/soundcloud_tracking.json` | Your account tracking data |
 
 ## Troubleshooting
 
-### Plugin not loading
+### "Not configured" error
 
-```bash
-openclaw plugins list
-openclaw gateway logs
-```
+Check your credentials file exists and has correct format:
 
-Check that:
-- Plugin shows as `enabled: true` in list
-- Gateway logs don't show errors
-
-Verify plugin directory exists:
 ```bash
-ls -la ~/.openclaw/extensions/soundcloud-watcher/
+cat ~/.openclaw/secrets/soundcloud.env
 ```
 
-### API rate limits
-
-If you hit rate limits:
-1. Increase `checkIntervalHours` in config (default: 6)
-2. Increase `dormantDays` to skip inactive artists sooner (default: 90)
-3. Check SoundCloud API status
-
-### No notifications
+Should contain:
+```
+SOUNDCLOUD_CLIENT_ID=...
+SOUNDCLOUD_CLIENT_SECRET=...
+MY_USERNAME=...
+```
 
-Check gateway session key in the plugin config (default is `agent:main:main`).
+### Plugin not loading
 
-Verify gateway is running:
 ```bash
-openclaw gateway status
+openclaw plugins list
 ```
 
-### Setup help
-
-Run `/soundcloud-setup` for detailed instructions with current config status.
+Should show `soundcloud-watcher` as `loaded`. If `disabled`:
 
-## Updating
-
-If installed via symlink (`-l`):
 ```bash
-cd /path/to/openclaw-soundcloud-watcher
-git pull
+openclaw plugins enable soundcloud-watcher
 openclaw gateway restart
 ```
 
-If installed from npm:
-```bash
-openclaw plugins install @akilles/soundcloud-watcher  # Gets latest
-openclaw gateway restart
-```
+### API rate limits
+
+The plugin handles rate limits automatically with exponential backoff. If issues persist, wait a few minutes and try again.
 
 ## Uninstalling
 
 ```bash
 openclaw plugins disable soundcloud-watcher
-openclaw plugins uninstall soundcloud-watcher
+rm -rf ~/.openclaw/extensions/soundcloud-watcher
 ```
 
-Clean up data (optional):
+Optionally remove data:
 ```bash
-rm -rf ~/.openclaw/data/soundcloud_tracking.json
-rm -rf ~/.openclaw/data/artists.json
-rm -rf ~/.openclaw/secrets/soundcloud.env
-rm -rf ~/.openclaw/soundcloud_backoff.json
+rm ~/.openclaw/secrets/soundcloud.env
+rm ~/.openclaw/data/artists.json
+rm ~/.openclaw/data/soundcloud_tracking.json
 ```
 
-## Support
+## Links
 
 - **GitHub:** https://github.com/wlinds/openclaw-soundcloud-watcher
-- **Issues:** https://github.com/wlinds/openclaw-soundcloud-watcher/issues
+- **npm:** https://www.npmjs.com/package/@akilles/soundcloud-watcher
 - **OpenClaw Docs:** https://docs.openclaw.ai/plugin
 
 ## License
 
-MIT - See [LICENSE](LICENSE) for details
+MIT

package/index.ts

@@ -10,6 +10,7 @@ interface PluginConfig {
   checkIntervalHours: number;
   myTracksLimit: number;
   dormantDays: number;
+  includeLinks: boolean;
   sessionKey?: string;
 }
 
@@ -34,6 +35,7 @@ function loadConfig(): PluginConfig | null {
         checkIntervalHours: 6,
         myTracksLimit: 10,
         dormantDays: 90,
+        includeLinks: env.INCLUDE_LINKS !== 'false',  // Default: true
         sessionKey: 'agent:main:main',
       };
     }
@@ -57,6 +59,7 @@ export default function register(api: any) {
       username: config.username,
       myTracksLimit: config.myTracksLimit,
       dormantDays: config.dormantDays,
+      includeLinks: config.includeLinks,
       logger: (...args: any[]) => logger.debug?.(...args) || console.log(...args),
     });
     return watcher;
@@ -178,5 +181,29 @@ MY_USERNAME=your_soundcloud_username
     },
   });
 
+  api.registerCommand({
+    name: 'soundcloud-cron',
+    description: 'Run check for cron (only outputs if there are updates)',
+    handler: async () => {
+      const w = getWatcher();
+      if (!w) {
+        (logger.warn ?? console.warn).call(logger, 'SoundCloud cron: not configured');
+        return { text: '' };  // Silent fail for cron
+      }
+      try {
+        const result = await w.runCron();
+        if (result) {
+          return { text: result };
+        }
+        // No updates - return empty (silent success)
+        (logger.debug ?? console.log).call(logger, 'SoundCloud cron: no updates');
+        return { text: '' };
+      } catch (e) {
+        (logger.error ?? console.error).call(logger, 'SoundCloud cron error:', e);
+        return { text: `SoundCloud check failed: ${e}` };
+      }
+    },
+  });
+
   (logger.info ?? console.log).call(logger, 'SoundCloud Watcher plugin loaded');
 }

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "soundcloud-watcher",
   "name": "SoundCloud Watcher",
   "description": "Monitor your SoundCloud account and track artist releases",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akilles/soundcloud-watcher",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "OpenClaw plugin to monitor SoundCloud account and track artist releases",
   "main": "index.ts",
   "openclaw": {

package/soundcloud_watcher.ts

@@ -56,12 +56,24 @@ export interface SoundCloudWatcherConfig {
   username: string;
   myTracksLimit?: number;
   dormantDays?: number;
+  includeLinks?: boolean;  // Include URLs in notifications (default: true)
   logger?: (...args: any[]) => void;
 }
 
 interface UserInfo {
   username: string;
   display_name: string;
+  permalink_url?: string;
+}
+
+interface FollowerNotification {
+  type: 'new' | 'lost';
+  users: UserInfo[];
+}
+
+interface AccountNotifications {
+  followers: FollowerNotification[];
+  engagement: string[];  // likes, reposts, etc.
 }
 
 interface TrackStats {
@@ -396,9 +408,11 @@ class SoundCloudAPI {
 
       for (const f of data.collection ?? []) {
         if (f && typeof f === "object" && "id" in f) {
+          const permalink = f.permalink ?? f.username ?? "unknown";
           followers[String(f.id)] = {
-            username: f.permalink ?? f.username ?? "unknown",
+            username: permalink,
             display_name: f.full_name ?? f.username ?? "unknown",
+            permalink_url: f.permalink_url ?? `https://soundcloud.com/${permalink}`,
           };
         }
       }
@@ -442,12 +456,12 @@ class AccountWatcher {
     writeJson(ACCOUNT_DATA, this.data);
   }
 
-  async check(): Promise<string[]> {
-    const notifications: string[] = [];
+  async check(): Promise<AccountNotifications> {
+    const result: AccountNotifications = { followers: [], engagement: [] };
 
     if (!this.data.my_account) {
       const user = await this.api.resolve(this.config.myUsername);
-      if (!user) return ["Failed to resolve SoundCloud user"];
+      if (!user) return result;
       this.data.my_account = {
         user_id: user.id,
         username: user.permalink ?? this.config.myUsername,
@@ -459,7 +473,7 @@ class AccountWatcher {
     const profile = await this.api.getUser(userId);
     if (!profile) {
       this.log("Failed to fetch profile, skipping account check");
-      return notifications;
+      return result;
     }
 
     const currentCount = num(profile.followers_count);
@@ -479,23 +493,16 @@ class AccountWatcher {
         if (Object.keys(stored).length) {
           const newFollowers = Object.entries(currentFollowers)
             .filter(([uid]) => !stored[uid])
-            .map(([, f]) => f.display_name);
+            .map(([, f]) => f);
           const lostFollowers = Object.entries(stored)
             .filter(([uid]) => !currentFollowers[uid])
-            .map(([, f]) => f.display_name);
+            .map(([, f]) => f);
 
           if (newFollowers.length) {
-            let names = newFollowers.slice(0, 3).join(", ");
-            if (newFollowers.length > 3) names += ` +${newFollowers.length - 3} more`;
-            notifications.push(
-              `New follower${newFollowers.length > 1 ? "s" : ""}: **${names}**`
-            );
+            result.followers.push({ type: 'new', users: newFollowers });
           }
           if (lostFollowers.length) {
-            const names = lostFollowers.slice(0, 3).join(", ");
-            notifications.push(
-              `Lost follower${lostFollowers.length > 1 ? "s" : ""}: ${names}`
-            );
+            result.followers.push({ type: 'lost', users: lostFollowers });
           }
         }
 
@@ -550,11 +557,11 @@ class AccountWatcher {
               let names = newLikerNames.slice(0, 3).join(", ");
               if (newLikerNames.length > 3)
                 names += ` +${newLikerNames.length - 3} more`;
-              notifications.push(`**${names}** liked '${title}'`);
+              result.engagement.push(`**${names}** liked '${title}'`);
             }
             if (unlikerNames.length) {
               const names = unlikerNames.slice(0, 3).join(", ");
-              notifications.push(`${names} unliked '${title}'`);
+              result.engagement.push(`${names} unliked '${title}'`);
             }
           } else {
             stats.likers = prevLikers;
@@ -562,7 +569,7 @@ class AccountWatcher {
 
           const newReposts = currentReposts - (prev.reposts ?? 0);
           if (newReposts > 0) {
-            notifications.push(
+            result.engagement.push(
               `'${title}' got ${newReposts} repost${newReposts > 1 ? "s" : ""}!`
             );
           }
@@ -579,7 +586,7 @@ class AccountWatcher {
     }
 
     this.save();
-    return notifications;
+    return result;
   }
 }
 
@@ -764,12 +771,14 @@ export class SoundCloudWatcher {
   private api: SoundCloudAPI;
   private myTracksLimit: number;
   private dormantDays: number;
+  private includeLinks: boolean;
   private log: (...args: any[]) => void;
 
   constructor(opts: SoundCloudWatcherConfig) {
     this.log = opts.logger ?? console.log;
     this.myTracksLimit = opts.myTracksLimit ?? 10;
     this.dormantDays = opts.dormantDays ?? 90;
+    this.includeLinks = opts.includeLinks ?? true;  // Default: include links
     this.config = new Config(opts.clientId, opts.clientSecret, opts.username);
     this.api = new SoundCloudAPI(this.config, this.log);
   }
@@ -827,11 +836,24 @@ export class SoundCloudWatcher {
     lines.push(`[${utcnow()}] Full check complete\n`);
 
     lines.push("--- Account ---");
-    for (const n of accountNotifs) lines.push(`  ${n}`);
-    if (!accountNotifs.length) lines.push("  No updates");
+    for (const fn of accountNotifs.followers) {
+      lines.push(...this.formatFollowerNotification(fn).map(l => `  ${l}`));
+    }
+    for (const e of accountNotifs.engagement) {
+      lines.push(`  ${e}`);
+    }
+    if (!accountNotifs.followers.length && !accountNotifs.engagement.length) {
+      lines.push("  No updates");
+    }
 
     lines.push("\n--- Artist Releases ---");
-    for (const r of releases) lines.push(`  ${r.artist}: ${r.title}`);
+    for (const r of releases) {
+      if (this.includeLinks && r.url) {
+        lines.push(`  ${r.artist}: ${r.title} - ${r.url}`);
+      } else {
+        lines.push(`  ${r.artist}: ${r.title}`);
+      }
+    }
     if (!releases.length) lines.push("  No new releases");
 
     lines.push(`\nAPI calls: ${this.api.calls}`);
@@ -868,6 +890,34 @@ export class SoundCloudWatcher {
     return tracker.list();
   }
 
+  private formatFollowerNotification(notif: FollowerNotification): string[] {
+    const lines: string[] = [];
+    const users = notif.users.slice(0, 5);  // Max 5 users shown
+    const remaining = notif.users.length - users.length;
+    
+    if (notif.type === 'new') {
+      lines.push(`New follower${notif.users.length > 1 ? 's' : ''}:`);
+      for (const u of users) {
+        if (this.includeLinks && u.permalink_url) {
+          lines.push(`- **${u.display_name}**: ${u.permalink_url}`);
+        } else {
+          lines.push(`- **${u.display_name}**`);
+        }
+      }
+    } else {
+      lines.push(`Lost follower${notif.users.length > 1 ? 's' : ''}:`);
+      for (const u of users) {
+        lines.push(`- ${u.display_name}`);
+      }
+    }
+    
+    if (remaining > 0) {
+      lines.push(`  ...and ${remaining} more`);
+    }
+    
+    return lines;
+  }
+
   async runCron(): Promise<string | null> {
     const tokenErr = await this.ensureToken();
     if (tokenErr) {
@@ -884,16 +934,31 @@ export class SoundCloudWatcher {
     ]);
 
     const lines: string[] = [];
-    if (accountNotifs.length) {
+    
+    // Format follower notifications
+    const hasFollowerUpdates = accountNotifs.followers.length > 0;
+    const hasEngagement = accountNotifs.engagement.length > 0;
+    
+    if (hasFollowerUpdates || hasEngagement) {
       lines.push("**Account:**");
-      lines.push(...accountNotifs.map((n) => `- ${n}`));
+      for (const fn of accountNotifs.followers) {
+        lines.push(...this.formatFollowerNotification(fn));
+      }
+      for (const e of accountNotifs.engagement) {
+        lines.push(`- ${e}`);
+      }
       lines.push("");
     }
+    
     if (releases.length) {
       lines.push("**New Releases:**");
       for (const r of releases) {
-        lines.push(`- **${r.artist}** dropped: ${r.title}`);
-        lines.push(`  ${r.url}`);
+        if (this.includeLinks && r.url) {
+          lines.push(`- **${r.artist}** dropped: ${r.title}`);
+          lines.push(`  ${r.url}`);
+        } else {
+          lines.push(`- **${r.artist}** dropped: ${r.title}`);
+        }
       }
       lines.push("");
     }