@akilles/soundcloud-watcher 2.0.5 → 2.2.0

package/README.md

@@ -48,6 +48,9 @@ Add your credentials:
 SOUNDCLOUD_CLIENT_ID=your_client_id
 SOUNDCLOUD_CLIENT_SECRET=your_client_secret
 MY_USERNAME=your_soundcloud_username
+
+# Optional settings
+INCLUDE_LINKS=true   # Include URLs in notifications (default: true)
 ```
 
 ### 4. Restart & Verify

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;

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.5",
+  "version": "2.2.0",
   "description": "OpenClaw plugin to monitor SoundCloud account and track artist releases",
   "main": "index.ts",
   "openclaw": {
@@ -44,5 +44,8 @@
   },
   "engines": {
     "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "typescript": "^5.9.3"
   }
 }

package/soundcloud_watcher.ts

@@ -25,6 +25,7 @@ const CONFIG_FILE = path.join(OPENCLAW_DIR, "secrets", "soundcloud.env");
 const ACCOUNT_DATA = path.join(OPENCLAW_DIR, "data", "soundcloud_tracking.json");
 const ARTISTS_DATA = path.join(OPENCLAW_DIR, "data", "artists.json");
 const BACKOFF_FILE = path.join(OPENCLAW_DIR, "soundcloud_backoff.json");
+const TOKEN_BACKOFF_FILE = path.join(OPENCLAW_DIR, "soundcloud_token_backoff.json");
 
 // =============================================================================
 // TUNING
@@ -40,6 +41,13 @@ const FOLLOWERS_PAGE_SIZE = 200;
 const BACKOFF_BASE_SECONDS = 300;
 const BACKOFF_MAX_SECONDS = 7200;
 
+// Token refresh has lower backoff - it's critical for operation
+const TOKEN_BACKOFF_BASE_SECONDS = 60;
+const TOKEN_BACKOFF_MAX_SECONDS = 300;  // 5 min max, not 2 hours
+
+// Proactive refresh buffer (refresh 5 min before expiry)
+const TOKEN_REFRESH_BUFFER_SECONDS = 300;
+
 const API_TIMEOUT_MS = 15_000;
 
 // =============================================================================
@@ -56,12 +64,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 {
@@ -215,6 +235,7 @@ class SoundCloudAPI {
     private log: (...args: any[]) => void
   ) {}
 
+  // -- API rate limit backoff (for 429s on regular API calls) --
   private checkBackoff(): number | null {
     const data = readJson<{ last_fail?: number; fail_count?: number }>(
       BACKOFF_FILE,
@@ -245,16 +266,75 @@ class SoundCloudAPI {
     if (fs.existsSync(BACKOFF_FILE)) fs.unlinkSync(BACKOFF_FILE);
   }
 
-  async refreshToken(): Promise<boolean> {
+  // -- Token refresh backoff (separate, shorter max) --
+  private checkTokenBackoff(): number | null {
+    const data = readJson<{ last_fail?: number; fail_count?: number }>(
+      TOKEN_BACKOFF_FILE,
+      {}
+    );
+    if (!data.last_fail) return null;
+    const elapsed = Date.now() / 1000 - data.last_fail;
+    const backoff = Math.min(
+      TOKEN_BACKOFF_BASE_SECONDS * 2 ** (data.fail_count ?? 0),
+      TOKEN_BACKOFF_MAX_SECONDS
+    );
+    return elapsed < backoff ? Math.floor(backoff - elapsed) : null;
+  }
+
+  private setTokenBackoff(): void {
+    try {
+      const data = readJson<{ fail_count?: number }>(TOKEN_BACKOFF_FILE, {});
+      writeJson(TOKEN_BACKOFF_FILE, {
+        fail_count: (data.fail_count ?? 0) + 1,
+        last_fail: Date.now() / 1000,
+      });
+    } catch {
+      /* best effort */
+    }
+  }
+
+  private clearTokenBackoff(): void {
+    if (fs.existsSync(TOKEN_BACKOFF_FILE)) fs.unlinkSync(TOKEN_BACKOFF_FILE);
+  }
+
+  // -- JWT helpers for proactive refresh --
+  private getTokenExpiry(): number | null {
+    const token = this.config.accessToken;
+    if (!token) return null;
+    try {
+      const parts = token.split(".");
+      if (parts.length !== 3) return null;
+      const payload = JSON.parse(Buffer.from(parts[1], "base64").toString());
+      return payload.exp ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  private isTokenExpiringSoon(): boolean {
+    const exp = this.getTokenExpiry();
+    if (!exp) return true; // No token or can't decode = refresh
+    const now = Date.now() / 1000;
+    return now > exp - TOKEN_REFRESH_BUFFER_SECONDS;
+  }
+
+  // -- Token refresh (with separate backoff, proactive check) --
+  async refreshToken(force = false): Promise<boolean> {
     if (!this.config.clientId || !this.config.clientSecret) return false;
 
-    const remaining = this.checkBackoff();
-    if (remaining) {
-      this.log(`Token refresh in backoff (${remaining}s remaining)`);
+    // Skip if token is still valid (unless forced, e.g., on 401)
+    if (!force && !this.isTokenExpiringSoon()) {
+      return true; // Token still good
+    }
+
+    const remaining = this.checkTokenBackoff();
+    if (remaining && !force) {
+      this.log(`Token refresh in backoff (${remaining}s remaining), skipping`);
       return false;
     }
 
     try {
+      this.log("Refreshing token...");
       const body = new URLSearchParams({
         grant_type: "client_credentials",
         client_id: this.config.clientId,
@@ -267,25 +347,35 @@ class SoundCloudAPI {
         signal: AbortSignal.timeout(API_TIMEOUT_MS),
       });
       if (resp.status === 429) {
-        this.setBackoff();
+        this.setTokenBackoff();
         this.log("Token refresh rate limited (429)");
         return false;
       }
       if (!resp.ok) {
+        this.setTokenBackoff();
         this.log(`Token refresh failed: ${resp.status}`);
         return false;
       }
       const result = (await resp.json()) as { access_token: string };
       this.config.saveToken(result.access_token);
-      this.clearBackoff();
-      this.log("Token refreshed");
+      this.clearTokenBackoff();
+      this.log("Token refreshed successfully");
       return true;
     } catch (e) {
-      this.log(`Token refresh failed: ${e}`);
+      this.setTokenBackoff();
+      this.log(`Token refresh error: ${e}`);
       return false;
     }
   }
 
+  // Proactive check - call before making API requests
+  async ensureValidToken(): Promise<boolean> {
+    if (this.isTokenExpiringSoon()) {
+      return this.refreshToken(false);
+    }
+    return true;
+  }
+
   async get(
     url: string,
     params?: Record<string, string | number>,
@@ -320,7 +410,8 @@ class SoundCloudAPI {
       });
 
       if (resp.status === 401 && retry) {
-        if (await this.refreshToken()) {
+        this.log("Got 401, forcing token refresh...");
+        if (await this.refreshToken(true)) {  // force=true bypasses backoff
           return this.get(url, params, false);
         }
       }
@@ -396,9 +487,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 +535,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 +552,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 +572,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 +636,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 +648,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 +665,7 @@ class AccountWatcher {
     }
 
     this.save();
-    return notifications;
+    return result;
   }
 }
 
@@ -764,20 +850,22 @@ 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);
   }
 
   private async ensureToken(): Promise<string | null> {
-    if (this.config.accessToken) return null;
-    if (!(await this.api.refreshToken())) {
-      return "Failed to get access token. Check your clientId and clientSecret.";
+    // Proactive refresh: check if token exists AND is not expiring soon
+    if (!(await this.api.ensureValidToken())) {
+      return "Failed to get/refresh access token. Check your clientId and clientSecret.";
     }
     return null;
   }
@@ -827,11 +915,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 +969,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 +1013,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("");
     }