@hidden-leaf/x-skill 1.0.0

package/scripts/oauth-flow.ts

@@ -0,0 +1,216 @@
+/**
+ * OAuth 2.0 Authorization Code Flow with PKCE for X API.
+ *
+ * Run once to get your User Access Token:
+ *   npx tsx scripts/oauth-flow.ts
+ *
+ * This will:
+ *   1. Generate a PKCE code challenge
+ *   2. Open your browser to X's authorize page
+ *   3. Start a local server to catch the callback
+ *   4. Exchange the auth code for a User Access Token
+ *   5. Print the token + user ID to paste into your .env
+ */
+
+import * as http from 'http';
+import * as crypto from 'crypto';
+import * as url from 'url';
+import * as dotenv from 'dotenv';
+
+dotenv.config();
+
+const CLIENT_ID = process.env.X_CONSUMER_KEY;
+const CLIENT_SECRET = process.env.X_CONSUMER_SECRET;
+const CALLBACK_URL = process.env.X_CALLBACK_URL || 'http://localhost:3000/callback';
+const SCOPES = ['bookmark.read', 'tweet.read', 'users.read', 'offline.access'];
+
+if (!CLIENT_ID || !CLIENT_SECRET) {
+  console.error('ERROR: X_CONSUMER_KEY and X_CONSUMER_SECRET must be set in .env');
+  process.exit(1);
+}
+
+// =============================================================================
+// PKCE helpers
+// =============================================================================
+
+function generateCodeVerifier(): string {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+function generateCodeChallenge(verifier: string): string {
+  return crypto.createHash('sha256').update(verifier).digest('base64url');
+}
+
+function generateState(): string {
+  return crypto.randomBytes(16).toString('hex');
+}
+
+// =============================================================================
+// Token exchange
+// =============================================================================
+
+async function exchangeCodeForToken(code: string, codeVerifier: string): Promise<{
+  access_token: string;
+  refresh_token?: string;
+  expires_in: number;
+  token_type: string;
+  scope: string;
+}> {
+  const params = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code,
+    redirect_uri: CALLBACK_URL,
+    code_verifier: codeVerifier,
+    client_id: CLIENT_ID!,
+  });
+
+  const basicAuth = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');
+
+  const response = await fetch('https://api.x.com/2/oauth2/token', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Authorization: `Basic ${basicAuth}`,
+    },
+    body: params.toString(),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Token exchange failed (${response.status}): ${text}`);
+  }
+
+  return response.json();
+}
+
+async function fetchUserId(accessToken: string): Promise<{ id: string; username: string; name: string }> {
+  const response = await fetch('https://api.x.com/2/users/me', {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Failed to fetch user info (${response.status}): ${text}`);
+  }
+
+  const data = await response.json() as { data: { id: string; username: string; name: string } };
+  return data.data;
+}
+
+// =============================================================================
+// Main flow
+// =============================================================================
+
+async function main(): Promise<void> {
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = generateCodeChallenge(codeVerifier);
+  const state = generateState();
+
+  // Build authorization URL
+  const authUrl = new URL('https://x.com/i/oauth2/authorize');
+  authUrl.searchParams.set('response_type', 'code');
+  authUrl.searchParams.set('client_id', CLIENT_ID!);
+  authUrl.searchParams.set('redirect_uri', CALLBACK_URL);
+  authUrl.searchParams.set('scope', SCOPES.join(' '));
+  authUrl.searchParams.set('state', state);
+  authUrl.searchParams.set('code_challenge', codeChallenge);
+  authUrl.searchParams.set('code_challenge_method', 'S256');
+
+  console.log('\n=== X API OAuth 2.0 Flow ===\n');
+  console.log('Open this URL in your browser:\n');
+  console.log(authUrl.toString());
+  console.log('\nWaiting for callback on http://localhost:3000...\n');
+
+  // Try to open browser automatically
+  try {
+    const { exec } = await import('child_process');
+    const openCmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
+    exec(`${openCmd} "${authUrl.toString()}"`);
+  } catch {
+    // Manual open is fine
+  }
+
+  // Start local server to catch callback
+  const code = await new Promise<string>((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      if (!req.url?.startsWith('/callback')) {
+        res.writeHead(404);
+        res.end('Not found');
+        return;
+      }
+
+      const parsed = url.parse(req.url, true);
+      const callbackState = parsed.query.state as string;
+      const callbackCode = parsed.query.code as string;
+      const error = parsed.query.error as string;
+
+      if (error) {
+        res.writeHead(400);
+        res.end(`Authorization error: ${error}`);
+        server.close();
+        reject(new Error(`Authorization denied: ${error}`));
+        return;
+      }
+
+      if (callbackState !== state) {
+        res.writeHead(400);
+        res.end('State mismatch — possible CSRF. Try again.');
+        server.close();
+        reject(new Error('State mismatch'));
+        return;
+      }
+
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(`
+        <html>
+          <body style="background: #15202B; color: #E7E9EA; font-family: system-ui; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0;">
+            <div style="text-align: center;">
+              <h1>Authorized!</h1>
+              <p>You can close this tab and return to the terminal.</p>
+            </div>
+          </body>
+        </html>
+      `);
+      server.close();
+      resolve(callbackCode);
+    });
+
+    server.listen(3000, () => {
+      // Server is ready
+    });
+
+    // Timeout after 5 minutes
+    setTimeout(() => {
+      server.close();
+      reject(new Error('Timeout — no callback received within 5 minutes'));
+    }, 300_000);
+  });
+
+  console.log('Authorization code received. Exchanging for token...\n');
+
+  // Exchange code for token
+  const token = await exchangeCodeForToken(code, codeVerifier);
+  console.log('Token received! Fetching user info...\n');
+
+  // Fetch user ID
+  const user = await fetchUserId(token.access_token);
+
+  console.log('=== SUCCESS ===\n');
+  console.log(`Authenticated as: ${user.name} (@${user.username})`);
+  console.log(`User ID: ${user.id}`);
+  console.log(`Token expires in: ${token.expires_in}s (~${Math.round(token.expires_in / 3600)}h)`);
+  console.log(`Scopes: ${token.scope}\n`);
+
+  console.log('Add these to your .env:\n');
+  console.log(`X_USER_ACCESS_TOKEN=${token.access_token}`);
+  console.log(`X_USER_ID=${user.id}`);
+  if (token.refresh_token) {
+    console.log(`X_REFRESH_TOKEN=${token.refresh_token}`);
+  }
+  console.log('\nDone! You can now run sync.\n');
+}
+
+main().catch((err) => {
+  console.error('OAuth flow failed:', err.message);
+  process.exit(1);
+});

package/scripts/postinstall.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * postinstall hook — auto-injects x-skill context into the
+ * consuming project's CLAUDE.md so Claude Code picks it up immediately.
+ *
+ * Safe to re-run: skips if the section already exists.
+ * Only runs when installed as a dependency (not during local dev).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MARKER = '<!-- @hidden-leaf/x-skill -->';
+
+const SNIPPET = `
+${MARKER}
+## X Bookmark Intelligence (Library-Based Skill)
+
+This project uses \`@hidden-leaf/x-skill\` — a TypeScript library for X (Twitter) bookmark intelligence.
+This is NOT an MCP tool or registered skill. To use it, write a TypeScript script and execute it with \`npx tsx <script>.ts\`.
+
+**Setup:** Credentials in \`.env\` — needs \`X_BEARER_TOKEN\`, \`X_USER_ID\`.
+See node_modules/@hidden-leaf/x-skill/.env.example for all options.
+
+**Skill reference:** Read node_modules/@hidden-leaf/x-skill/SKILL.md for the full API before using.
+
+**How to use:** Write a .ts script, then run it:
+\`\`\`typescript
+import { createBookmarksSkillFromEnv } from '@hidden-leaf/x-skill';
+const skill = createBookmarksSkillFromEnv();
+
+// List folders: await skill.listFolders()
+// Fetch posts: await skill.fetchByFolderName('Robotics')
+// Research brief: await skill.brief({ folderName: 'AI MEDICINE', hlnContext: ['Applied AI Studio'] })
+\`\`\`
+Then execute: \`npx tsx <script>.ts\`
+<!-- /@hidden-leaf/x-skill -->
+`.trimStart();
+
+function findProjectRoot() {
+  // Walk up from node_modules/@hidden-leaf/x-skill/scripts/
+  let dir = __dirname;
+  for (let i = 0; i < 10; i++) {
+    dir = path.dirname(dir);
+    const pkg = path.join(dir, 'package.json');
+    if (fs.existsSync(pkg)) {
+      try {
+        const json = JSON.parse(fs.readFileSync(pkg, 'utf8'));
+        // Don't modify our own repo
+        if (json.name === '@hidden-leaf/x-skill') continue;
+        return dir;
+      } catch {
+        continue;
+      }
+    }
+  }
+  return null;
+}
+
+function run() {
+  // Skip during local development (npm install in the skill repo itself)
+  const ownPkg = path.resolve(__dirname, '..', 'package.json');
+  if (fs.existsSync(ownPkg)) {
+    try {
+      const json = JSON.parse(fs.readFileSync(ownPkg, 'utf8'));
+      if (json.name === '@hidden-leaf/x-skill') {
+        // Check if we're in node_modules (installed as dep) or at repo root (local dev)
+        if (!__dirname.includes('node_modules')) return;
+      }
+    } catch {
+      // continue
+    }
+  }
+
+  const root = findProjectRoot();
+  if (!root) return;
+
+  const claudeMd = path.join(root, 'CLAUDE.md');
+
+  if (fs.existsSync(claudeMd)) {
+    const existing = fs.readFileSync(claudeMd, 'utf8');
+    if (existing.includes(MARKER)) {
+      // Already injected — skip
+      return;
+    }
+    // Append to existing CLAUDE.md
+    fs.writeFileSync(claudeMd, existing.trimEnd() + '\n\n' + SNIPPET);
+    console.log('[@hidden-leaf/x-skill] Added X bookmark intelligence section to CLAUDE.md');
+    console.log('[@hidden-leaf/x-skill] Restart Claude Code to activate the skill (CLAUDE.md is loaded at session start)');
+  } else {
+    // Create new CLAUDE.md
+    fs.writeFileSync(claudeMd, SNIPPET);
+    console.log('[@hidden-leaf/x-skill] Created CLAUDE.md with X bookmark intelligence');
+    console.log('[@hidden-leaf/x-skill] Restart Claude Code to activate the skill (CLAUDE.md is loaded at session start)');
+  }
+
+  // Copy .env.example if no .env exists
+  const envFile = path.join(root, '.env');
+  if (!fs.existsSync(envFile)) {
+    const envExample = path.resolve(__dirname, '..', '.env.example');
+    if (fs.existsSync(envExample)) {
+      fs.copyFileSync(envExample, envFile);
+      console.log('[@hidden-leaf/x-skill] Created .env from template — fill in your X API credentials');
+    }
+  }
+}
+
+try {
+  run();
+} catch {
+  // postinstall should never break npm install
+}

package/scripts/sync-test.ts

@@ -0,0 +1,36 @@
+/**
+ * First sync test — pulls all bookmark folders + tweets into local cache.
+ */
+import { createBookmarksSkillFromEnv } from '../src/skills/bookmarks/index.js';
+
+async function main() {
+  const skill = createBookmarksSkillFromEnv();
+
+  console.log('Syncing all bookmark folders from X API...\n');
+
+  const result = await skill.syncAll();
+
+  console.log(`Synced at: ${result.syncedAt}`);
+  console.log(`Folders: ${result.totalFolders}`);
+  console.log(`Total tweets: ${result.totalTweets}\n`);
+
+  for (const folder of result.folders) {
+    console.log(`  ${folder.name} — ${folder.tweetCount} tweets`);
+  }
+
+  console.log('\nCache stats:');
+  const stats = skill.stats();
+  console.log(`  Folders: ${stats.folders}`);
+  console.log(`  Tweets: ${stats.tweets}`);
+  console.log(`  Users: ${stats.users}`);
+  console.log(`  Last sync: ${stats.lastSync}`);
+
+  skill.close();
+  console.log('\nDone!');
+}
+
+main().catch((err) => {
+  console.error('Sync failed:', err.message);
+  if (err.status) console.error(`Status: ${err.status}`);
+  process.exit(1);
+});

package/scripts/test-refresh-forced.ts

@@ -0,0 +1,29 @@
+/**
+ * Force-test auto-refresh by using an invalid access token.
+ * The client should detect 401, refresh using the refresh token, and succeed.
+ */
+import * as dotenv from 'dotenv';
+dotenv.config();
+import { XClient } from '../src/clients/x-client.js';
+
+async function main() {
+  console.log('Force-testing auto-refresh with expired/invalid token...\n');
+
+  const client = new XClient({
+    userAccessToken: 'deliberately_invalid_token_to_trigger_401',
+    userId: process.env.X_USER_ID!,
+    refreshToken: process.env.X_REFRESH_TOKEN,
+    consumerKey: process.env.X_CONSUMER_KEY,
+    consumerSecret: process.env.X_CONSUMER_SECRET,
+  });
+
+  const me = await client.getMe();
+
+  console.log(`\nAuthenticated as: ${me.data.name} (@${me.data.username})`);
+  console.log('Auto-refresh worked — recovered from expired token!');
+}
+
+main().catch((err) => {
+  console.error('Failed:', err.message);
+  process.exit(1);
+});

package/scripts/test-refresh.ts

@@ -0,0 +1,25 @@
+/**
+ * Test auto-refresh: calls /users/me.
+ * If token is expired, it should auto-refresh and succeed.
+ */
+import * as dotenv from 'dotenv';
+dotenv.config();
+import { createXClientFromEnv } from '../src/clients/x-client.js';
+
+async function main() {
+  console.log('Testing auto-refresh...');
+  console.log(`Refresh token present: ${!!process.env.X_REFRESH_TOKEN}`);
+  console.log(`Consumer key present: ${!!process.env.X_CONSUMER_KEY}`);
+  console.log(`Consumer secret present: ${!!process.env.X_CONSUMER_SECRET}\n`);
+
+  const client = createXClientFromEnv();
+  const me = await client.getMe();
+
+  console.log(`Authenticated as: ${me.data.name} (@${me.data.username})`);
+  console.log('Auto-refresh is working!');
+}
+
+main().catch((err) => {
+  console.error('Failed:', err.message);
+  process.exit(1);
+});