feat(band): add Band.us adapter — bands, posts, mentions, post commands

docs/.vitepress/config.mts

@@ -68,6 +68,7 @@ export default defineConfig({
                 { text: 'Jimeng', link: '/adapters/browser/jimeng' },
                 { text: 'Yollomi', link: '/adapters/browser/yollomi' },
                 { text: 'LINUX DO', link: '/adapters/browser/linux-do' },
+                { text: 'Band', link: '/adapters/browser/band' },
                 { text: 'Chaoxing', link: '/adapters/browser/chaoxing' },
                 { text: 'Grok', link: '/adapters/browser/grok' },
                 { text: 'WeRead', link: '/adapters/browser/weread' },

docs/adapters/browser/band.md

@@ -0,0 +1,63 @@
+# Band
+
+**Mode**: 🔐 Browser · **Domain**: `www.band.us`
+
+Read posts, comments, and notifications from [Band](https://www.band.us), a private community platform. Authentication uses your logged-in Chrome session (cookie-based).
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli band bands` | List all Bands you belong to |
+| `opencli band posts <band_no>` | List posts from a Band |
+| `opencli band post <band_no> <post_no>` | Export full post content including nested comments |
+| `opencli band mentions` | Show notifications where you were @mentioned |
+
+## Usage Examples
+
+```bash
+# List all your bands (get band_no from here)
+opencli band bands
+
+# List recent posts in a band
+opencli band posts 12345678 --limit 10
+
+# Export a post with comments
+opencli band post 12345678 987654321
+
+# Export post body only (skip comments)
+opencli band post 12345678 987654321 --comments false
+
+# Export post and download attached photos
+opencli band post 12345678 987654321 --output ./band-photos
+
+# Show recent @mention notifications
+opencli band mentions --limit 20
+
+# Show only unread mentions
+opencli band mentions --unread true
+
+# Show all notification types
+opencli band mentions --filter all
+```
+
+### `band mentions` filter options
+
+| Filter | Description |
+|--------|-------------|
+| `mentioned` | Only notifications where you were @mentioned (default) |
+| `all` | All notifications |
+| `post` | Post-related notifications |
+| `comment` | Comment-related notifications |
+
+## Prerequisites
+
+- Chrome running and **logged into** [band.us](https://www.band.us)
+- [Browser Bridge extension](/guide/browser-bridge) installed
+
+## Notes
+
+- `band_no` is the numeric ID in the Band URL: `band.us/band/{band_no}/post`
+- `band bands` lists all your bands with their `band_no` values
+- `band post` output rows: `type=post` (the post itself), `type=comment` (top-level comment), `type=reply` (nested reply)
+- Photo downloads use the full-resolution URL (thumbnail query params are stripped automatically)

src/clis/band/bands.ts

@@ -0,0 +1,76 @@
+import { AuthRequiredError, EmptyResultError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+
+/**
+ * band bands — List all Bands you belong to.
+ *
+ * Band.us renders the full band list in the left sidebar of the home page for
+ * logged-in users, so we can extract everything we need from the DOM without
+ * XHR interception or any secondary navigation.
+ *
+ * Each sidebar item is an <a href="/band/{band_no}/..."> link whose text and
+ * data attributes carry the band name and member count.
+ */
+cli({
+  site: 'band',
+  name: 'bands',
+  description: 'List all Bands you belong to',
+  domain: 'www.band.us',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [],
+  columns: ['band_no', 'name', 'members'],
+
+  func: async (page, _kwargs) => {
+    const cookies = await page.getCookies({ domain: 'band.us' });
+    const isLoggedIn = cookies.some(c => c.name === 'band_session');
+    if (!isLoggedIn) throw new AuthRequiredError('band.us', 'Not logged in to Band');
+
+    // Extract the band list from the sidebar. Poll until at least one band card
+    // appears (React hydration may take a moment after navigation).
+    // Sidebar band cards use class "bandCover _link" with hrefs like /band/{id}/post.
+    const bands: { band_no: number; name: string; members: number }[] = await page.evaluate(`
+      (async () => {
+        const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+        // Wait up to 9 s for sidebar band cards to render.
+        for (let i = 0; i < 30; i++) {
+          if (document.querySelector('a.bandCover._link')) break;
+          await sleep(300);
+        }
+
+        const norm = s => (s || '').replace(/\\s+/g, ' ').trim();
+        const seen = new Set();
+        const results = [];
+
+        for (const a of Array.from(document.querySelectorAll('a.bandCover._link'))) {
+          // Extract band_no from href: /band/{id} or /band/{id}/post only.
+          const m = (a.getAttribute('href') || '').match(/^\\/band\\/(\\d+)(?:\\/post)?\\/?$/);
+          if (!m) continue;
+          const bandNo = Number(m[1]);
+          if (seen.has(bandNo)) continue;
+          seen.add(bandNo);
+
+          // Band name lives in p.uriText inside div.bandName.
+          const nameEl = a.querySelector('p.uriText');
+          const name = nameEl ? norm(nameEl.textContent) : '';
+          if (!name) continue;
+
+          // Member count is the <em> inside span.member.
+          const memberEl = a.querySelector('span.member em');
+          const members = memberEl ? parseInt((memberEl.textContent || '').replace(/[^0-9]/g, ''), 10) || 0 : 0;
+
+          results.push({ band_no: bandNo, name, members });
+        }
+
+        return results;
+      })()
+    `);
+
+    if (!bands || bands.length === 0) {
+      throw new EmptyResultError('band bands', 'No bands found in sidebar — are you logged in?');
+    }
+
+    return bands;
+  },
+});

src/clis/band/mentions.ts

@@ -0,0 +1,134 @@
+import { AuthRequiredError, EmptyResultError, SelectorError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+
+/**
+ * band mentions — Show Band notifications where you were @mentioned.
+ *
+ * Band.us signs every API request with a per-request HMAC (`md` header) generated
+ * by its own JavaScript, so we cannot replicate it externally. Instead we use
+ * Strategy.INTERCEPT: install an XHR interceptor, open the notification panel by
+ * clicking the bell to trigger the get_news XHR call, then apply client-side
+ * filtering to extract notifications matching the requested filter/unread options.
+ */
+cli({
+  site: 'band',
+  name: 'mentions',
+  description: 'Show Band notifications where you are @mentioned',
+  domain: 'www.band.us',
+  strategy: Strategy.INTERCEPT,
+  browser: true,
+  args: [
+    {
+      name: 'filter',
+      default: 'mentioned',
+      choices: ['mentioned', 'all', 'post', 'comment'],
+      help: 'Filter: mentioned (default) | all | post | comment',
+    },
+    { name: 'limit', type: 'int', default: 20, help: 'Max results' },
+    { name: 'unread', type: 'bool', default: false, help: 'Show only unread notifications' },
+  ],
+  columns: ['time', 'band', 'type', 'from', 'text', 'url'],
+
+  func: async (page, kwargs) => {
+    const filter = kwargs.filter as string;
+    const limit = kwargs.limit as number;
+    const unreadOnly = kwargs.unread as boolean;
+
+    // Navigate with a timestamp param to force a fresh page load each run.
+    // Without this, same-URL navigation may skip the reload (preserving the JS context
+    // and leaving the notification panel open from a previous run).
+    await page.goto(`https://www.band.us/?_=${Date.now()}`);
+
+    const cookies = await page.getCookies({ domain: 'band.us' });
+    const isLoggedIn = cookies.some(c => c.name === 'band_session');
+    if (!isLoggedIn) throw new AuthRequiredError('band.us', 'Not logged in to Band');
+
+    // Install XHR interceptor before any clicks so all get_news responses are captured.
+    await page.installInterceptor('get_news');
+
+    // Wait for the bell button to appear (React hydration) instead of a fixed sleep.
+    let bellReady = false;
+    for (let i = 0; i < 20; i++) {
+      const exists = await page.evaluate(`() => !!document.querySelector('button._btnWidgetIcon')`);
+      if (exists) { bellReady = true; break; }
+      await page.wait(0.5);
+    }
+    if (!bellReady) {
+      throw new SelectorError('button._btnWidgetIcon', 'Notification bell not found. The Band.us UI may have changed.');
+    }
+
+    // Poll until a capture containing result_data.news arrives, up to maxSecs seconds.
+    // getInterceptedRequests() clears the array on each call, so captures are accumulated
+    // locally. The interceptor pattern 'get_news' also matches 'get_news_count' responses
+    // which don't have result_data.news — keep polling until the real news response arrives.
+    const waitForOneCapture = async (maxSecs = 8): Promise<any[]> => {
+      const captures: any[] = [];
+      for (let i = 0; i < maxSecs * 2; i++) {
+        await page.wait(0.5); // 0.5 seconds per iteration (page.wait takes seconds)
+        const reqs = await page.getInterceptedRequests();
+        if (reqs.length > 0) {
+          captures.push(...reqs);
+          if (captures.some((r: any) => Array.isArray(r?.result_data?.news))) return captures;
+        }
+      }
+      return captures;
+    };
+
+    // Click the bell. Guard against the element disappearing between the readiness
+    // check and the click (e.g. due to a React re-render) to surface a clear error.
+    const bellClicked = await page.evaluate(`() => {
+      const el = document.querySelector('button._btnWidgetIcon');
+      if (!el) return false;
+      el.click();
+      return true;
+    }`);
+    if (!bellClicked) {
+      throw new SelectorError('button._btnWidgetIcon', 'Notification bell disappeared before click. The Band.us UI may have changed.');
+    }
+
+    const requests = await waitForOneCapture();
+
+    // Find the get_news response (has result_data.news); get_news_count responses do not.
+    const newsReq = requests.find((r: any) => Array.isArray(r?.result_data?.news)) as any;
+    if (!newsReq) {
+      throw new EmptyResultError('band mentions', 'Failed to capture get_news response from Band.us. Try running the command again.');
+    }
+    let items: any[] = newsReq.result_data.news ?? [];
+
+    if (items.length === 0) {
+      throw new EmptyResultError('band mentions', 'No notifications found');
+    }
+
+    // Apply filters client-side from the full notification list.
+    if (unreadOnly) {
+      items = items.filter((n: any) => n.is_new === true);
+    }
+    if (filter === 'mentioned') {
+      // 'filters' is Band's server-side tag array; 'referred' means you were @mentioned.
+      items = items.filter((n: any) => n.filters?.includes('referred'));
+    } else if (filter === 'post') {
+      items = items.filter((n: any) => n.category === 'post');
+    } else if (filter === 'comment') {
+      items = items.filter((n: any) => n.category === 'comment');
+    }
+
+    // Band markup tags (<band:mention uid="...">, <band:sticker>, etc.) appear in
+    // notification text; strip them to get plain readable content.
+    const stripBandTags = (s: string) => s.replace(/<\/?band:[^>]+>/g, '');
+
+    return items.slice(0, limit).map((n: any) => {
+      const ts = n.created_at ? new Date(n.created_at) : null;
+      return {
+        time: ts
+          ? ts.toLocaleString('ja-JP', { month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' })
+          : '',
+        band: n.band?.name ?? '',
+        // 'filters' is Band's server-side tag array; 'referred' means you were @mentioned.
+        type: n.filters?.includes('referred') ? '@mention' : n.category ?? '',
+        from: n.actor?.name ?? '',
+        text: stripBandTags(n.subtext ?? '').slice(0, 100),
+        url: n.action?.pc ?? '',
+      };
+    });
+  },
+});