@1dolinski/fastforms 0.4.0 → 0.5.0

package/README.md

@@ -8,8 +8,8 @@ Fill any form fast. Manage multiple personas locally, pick the right ones at fil
 # 1. Create your first user + business persona
 npx @1dolinski/fastforms init
 
-# 2. Add a form persona (org context + form-specific answers)
-npx @1dolinski/fastforms add form
+# 2. Or import from Twitter (requires PRIVATE_KEY for x402 payment)
+npx @1dolinski/fastforms import twitter <your-handle>
 
 # 3. Enable remote debugging in Chrome
 #    Open chrome://inspect/#remote-debugging and toggle it on
@@ -21,16 +21,17 @@ npx @1dolinski/fastforms fill https://example.com/apply
 ## How it works
 
 1. **`fastforms init`** walks you through creating user + business personas interactively
-2. **`fastforms add form`** captures the form's org, purpose, and form-specific answers
-3. Personas are saved as individual JSON files in `.fastforms/`
-4. **`fastforms fill <url>`** connects to Chrome, picks personas, fills by label matching
-5. Form personas auto-match by URL — no need to specify which one
+2. **`fastforms import twitter`** pulls your profile from Twitter via x402 micropayment
+3. **`fastforms add form`** captures the form's org, purpose, and form-specific answers
+4. Personas are saved as individual JSON files in `.fastforms/`
+5. **`fastforms fill <url>`** connects to Chrome, picks personas, fills by label matching
 6. **Review and submit manually** in Chrome
 
 ## Requirements
 
 - Chrome >= 144
 - Node.js >= 18
+- (Optional) `PRIVATE_KEY` env var for Twitter import — Base network wallet with USDC
 
 ## Persona types
 
@@ -40,13 +41,14 @@ npx @1dolinski/fastforms fill https://example.com/apply
 | **Business** | What you're building | Company, product, traction, one-liner |
 | **Form** | Who's asking & why | Org, purpose, form-specific answers |
 
-Form persona facts **override** user/business data. "What attracts you to Nitro" belongs on the Nitro form persona, not on your user persona.
+Form persona facts **override** user/business data. Form-specific questions like "why this accelerator" belong on the form persona, not your user persona.
 
 ## Commands
 
 | Command | Description |
 |---|---|
 | `fastforms init` | Create your first user + business persona |
+| `fastforms import twitter <handle>` | Import user persona from Twitter via x402 |
 | `fastforms add user` | Add another user persona |
 | `fastforms add business` | Add another business persona |
 | `fastforms add form` | Add a form persona (org + answers) |
@@ -72,69 +74,84 @@ Form persona facts **override** user/business data. "What attracts you to Nitro"
 ```
 .fastforms/
   users/
-    chris.json
-    work-chris.json
+    jane.json
+    work-jane.json
   businesses/
-    apinow.json
-    sideproject.json
+    acme-labs.json
+    side-project.json
   forms/
-    nitro-accelerator.json
     yc-application.json
+    grant-proposal.json
   defaults.json
 ```
 
-### User persona (`users/chris.json`)
+### User persona (`users/jane.json`)
 
 ```json
 {
-  "name": "chris",
-  "fullName": "Chris Dolinski",
-  "email": "chris@example.com",
-  "role": "Founder",
-  "location": "Toronto, ON",
-  "linkedIn": "linkedin.com/in/1dolinski",
-  "github": "github.com/1dolinski",
-  "bio": "Serial entrepreneur",
+  "name": "jane",
+  "fullName": "Jane Smith",
+  "email": "jane@example.com",
+  "role": "Founder & CEO",
+  "location": "San Francisco, CA",
+  "linkedIn": "linkedin.com/in/janesmith",
+  "github": "github.com/janesmith",
+  "bio": "Building developer tools. Previously at Stripe.",
   "facts": {
-    "x handle": "@1dolinski",
-    "telegram": "@chris"
+    "x handle": "@janesmith",
+    "telegram": "@jane"
   }
 }
 ```
 
-### Business persona (`businesses/apinow.json`)
+### Business persona (`businesses/acme-labs.json`)
 
 ```json
 {
-  "name": "APINow.fun",
-  "oneLiner": "x402 everything",
-  "website": "apinow.fun",
-  "problem": "Payments are broken",
-  "solution": "Fix them with x402"
+  "name": "Acme Labs",
+  "oneLiner": "AI-powered form automation",
+  "website": "acmelabs.dev",
+  "problem": "Filling out repetitive applications wastes hours",
+  "solution": "Smart persona-based form filling"
 }
 ```
 
-### Form persona (`forms/nitro-accelerator.json`)
+### Form persona (`forms/yc-application.json`)
 
 ```json
 {
-  "name": "Nitro Accelerator",
-  "urls": ["nitroacc.xyz"],
-  "organization": "Nitro",
-  "purpose": "Crypto accelerator application for early-stage founders",
-  "notes": "NYC-based, 1-month residency",
+  "name": "YC Application",
+  "urls": ["apply.ycombinator.com"],
+  "organization": "Y Combinator",
+  "purpose": "Startup accelerator application",
+  "notes": "3-month program in SF, $500k investment",
   "deadline": "2026-04-01",
   "facts": {
-    "attracts": "The density of high-signal founders and the NYC residency",
-    "mentor": "Vitalik — his work on public goods aligns with our mission",
-    "spend": "Engineering hires and infrastructure for mainnet launch",
-    "last week": "Shipped v2 of the API, onboarded 3 beta customers"
+    "why this accelerator": "The alumni network and partner expertise in developer tools",
+    "spend": "Engineering hires and go-to-market",
+    "last week": "Launched beta, onboarded 50 users, 30% week-over-week growth"
   }
 }
 ```
 
 The `facts` on a form persona are form-specific answers keyed by label hints. They override user/business data when a form field matches.
 
+## Twitter import (x402)
+
+Pull your Twitter profile into a user persona with a single command. Uses the [x402 protocol](https://x402.org/) for pay-per-call access ($0.01 USDC on Base).
+
+```bash
+# Set your Base wallet private key
+export PRIVATE_KEY=0x...
+
+# Import your Twitter profile
+npx @1dolinski/fastforms import twitter janesmith
+```
+
+This creates `users/janesmith.json` pre-filled with your name, bio, location, and handle from Twitter. You can then `fastforms edit` to add more details.
+
+Requires a Base network wallet with USDC. Powered by [APINow.fun](https://apinow.fun).
+
 ## Web app (optional)
 
 You can also manage personas in the web UI at [293-fastforms.vercel.app/persona](https://293-fastforms.vercel.app/persona) and use `--web` flag to pull from there. The web app has an "Export for CLI" button to download your personas as local JSON files.

package/SKILL.md

@@ -12,6 +12,7 @@ Use this skill when the user says any of:
 - "use fastforms", "fastforms fill"
 - "set up my personas", "init fastforms"
 - "add a persona", "add a form persona"
+- "import from twitter", "pull my twitter profile"
 
 ## What it does
 
@@ -21,17 +22,22 @@ Use this skill when the user says any of:
    - **User** — who you are (name, email, bio, skills)
    - **Business** — what you're building (company, product, traction)
    - **Form** — who's asking and why (org, purpose, form-specific answers)
-2. Connects to Chrome via the DevTools Protocol
-3. Lets you pick which user + business + form persona to use at fill time
-4. Fills any form using label-matching — never submits
+2. Can import user personas from Twitter via x402 micropayment
+3. Connects to Chrome via the DevTools Protocol
+4. Lets you pick which user + business + form persona to use at fill time
+5. Fills any form using label-matching — never submits
 
 ## Quick start
 
 ```bash
-# 1. Create your first user + business persona
+# 1. Create your first personas
 npx @1dolinski/fastforms init
 
-# 2. Add a form persona with org context and form-specific answers
+# Or import from Twitter ($0.01 USDC on Base)
+export PRIVATE_KEY=0x...
+npx @1dolinski/fastforms import twitter <your-handle>
+
+# 2. Add form-specific context
 npx @1dolinski/fastforms add form
 
 # 3. Enable remote debugging in Chrome
@@ -47,6 +53,10 @@ npx @1dolinski/fastforms fill https://example.com/apply
 
 Walks through creating a user + business persona (optionally a form persona too).
 
+### `npx @1dolinski/fastforms import twitter <username>`
+
+Imports a user persona from Twitter via x402 micropayment ($0.01 USDC on Base). Requires `PRIVATE_KEY` env var set to a Base wallet private key.
+
 ### `npx @1dolinski/fastforms add user|business|form`
 
 Add another persona of any type.
@@ -84,9 +94,9 @@ Who you are. Name, email, role, GitHub, LinkedIn, bio, custom facts.
 What you're building. Company, product, one-liner, traction, business model.
 
 ### Form persona
-Who's asking and why. The organization that owns the form, the form's purpose, and **form-specific answers** that override user/business data. For example, "what attracts you to Nitro" is a Nitro-specific answer — it belongs on the form persona, not on your user or business persona.
+Who's asking and why. The organization that owns the form, the form's purpose, and **form-specific answers** that override user/business data.
 
-Form personas auto-match by URL. If your form persona has `urls: ["nitroacc.xyz"]` and you fill `https://nitroacc.xyz/apply`, it auto-selects.
+Form personas auto-match by URL. If your form persona has `urls: ["apply.ycombinator.com"]` and you fill that URL, it auto-selects.
 
 ## How it works
 
@@ -108,6 +118,12 @@ When the user asks you to fill a form:
 4. If Chrome debugging isn't enabled, tell the user to open `chrome://inspect/#remote-debugging`
 5. After filling, tell the user to review in Chrome and submit manually
 
+When the user wants to import from Twitter:
+
+1. They need `PRIVATE_KEY` set (Base wallet with USDC)
+2. Run `npx @1dolinski/fastforms import twitter <handle>`
+3. The persona will be saved to `.fastforms/users/<handle>.json`
+
 When the user wants to add a persona:
 
 1. Run `npx @1dolinski/fastforms add user|business|form`

package/bin/fastforms.js

@@ -3,7 +3,7 @@
 import { createInterface } from "readline";
 import { join } from "path";
 import { homedir } from "os";
-import { existsSync } from "fs";
+import { existsSync, readFileSync } from "fs";
 
 import { ensureChromeReady } from "../lib/chrome.js";
 import {
@@ -32,6 +32,17 @@ import {
   formTemplate,
 } from "../lib/local.js";
 
+// Load .env files for PRIVATE_KEY (used by x402 twitter import)
+function loadEnvFile(path) {
+  if (!existsSync(path)) return;
+  for (const line of readFileSync(path, "utf-8").split("\n")) {
+    const match = line.match(/^\s*([\w]+)\s*=\s*(.+?)\s*$/);
+    if (match && !process.env[match[1]]) process.env[match[1]] = match[2];
+  }
+}
+loadEnvFile(join(process.cwd(), ".fastforms", ".env"));
+loadEnvFile(join(process.cwd(), ".env"));
+
 const args = process.argv.slice(2);
 const command = args[0];
 
@@ -69,16 +80,14 @@ function help() {
   fastforms — Fill any form fast, with multiple personas.
 
   Usage:
-    fastforms init                  Create your first user + business persona
-    fastforms add user              Add another user persona
-    fastforms add business          Add another business persona
-    fastforms add form              Add a form persona (org + purpose + answers)
-    fastforms list                  List all personas
-    fastforms edit                  Edit an existing persona
-    fastforms remove                Remove a persona
-    fastforms fill <url>            Fill a form (pick personas interactively)
-    fastforms personas              Open web persona manager in Chrome
-    fastforms                       Show this help
+    fastforms init                        Create your first user + business persona
+    fastforms import twitter <handle>     Import user persona from Twitter (x402)
+    fastforms add user|business|form      Add another persona
+    fastforms list                        List all personas
+    fastforms edit                        Edit an existing persona
+    fastforms remove                      Remove a persona
+    fastforms fill <url>                  Fill a form (pick personas interactively)
+    fastforms personas                    Open web persona manager in Chrome
 
   Options:
     --web               Use web app personas instead of local .fastforms/
@@ -93,9 +102,13 @@ function help() {
     business  — what you're building (company, product, traction)
     form      — who's asking and why (org, purpose, form-specific answers)
 
+  Twitter import:
+    Requires PRIVATE_KEY env var (Base wallet with USDC, $0.01/call).
+    Set in .env, .fastforms/.env, or export directly.
+
   Quick start:
     1. npx @1dolinski/fastforms init
-    2. npx @1dolinski/fastforms add form          # add form-specific context
+    2. npx @1dolinski/fastforms add form
     3. Enable remote debugging: chrome://inspect/#remote-debugging
     4. npx @1dolinski/fastforms fill https://example.com/apply
 `);
@@ -605,6 +618,52 @@ async function openPersonas() {
   browser.disconnect();
 }
 
+// ---------------------------------------------------------------------------
+// import — pull persona from external source
+// ---------------------------------------------------------------------------
+
+async function importPersona() {
+  const source = args[1];
+  const handle = args[2];
+
+  if (source !== "twitter" || !handle) {
+    console.error("  Usage: fastforms import twitter <handle>\n");
+    console.error("  Requires PRIVATE_KEY env var (Base wallet with USDC).");
+    console.error("  Set in .env, .fastforms/.env, or: export PRIVATE_KEY=0x...\n");
+    process.exit(1);
+  }
+
+  console.log(`\n  fastforms import — Twitter → user persona\n`);
+
+  let fetchTwitterProfile, twitterToPersona;
+  try {
+    ({ fetchTwitterProfile, twitterToPersona } = await import("../lib/x402.js"));
+  } catch (e) {
+    console.error("  Failed to load x402 module:", e.message);
+    console.error("\n  Make sure dependencies are installed:");
+    console.error("    npm install viem @x402/fetch @x402/evm\n");
+    process.exit(1);
+  }
+
+  const data = await fetchTwitterProfile(handle);
+  const persona = twitterToPersona(data, handle);
+
+  console.log(`\n  Twitter profile for @${handle}:`);
+  if (persona.fullName) console.log(`    Name: ${persona.fullName}`);
+  if (persona.bio) console.log(`    Bio: ${persona.bio.slice(0, 80)}${persona.bio.length > 80 ? "..." : ""}`);
+  if (persona.location) console.log(`    Location: ${persona.location}`);
+  if (persona.portfolio) console.log(`    Website: ${persona.portfolio}`);
+  const factCount = Object.keys(persona.facts || {}).length;
+  if (factCount) console.log(`    Facts: ${factCount}`);
+
+  const dir = resolveDir();
+  ensureDir(dir);
+  const slug = saveUserPersona(dir, persona);
+  console.log(`\n  Saved to ${dir}/users/${slug}.json`);
+  console.log("  Run 'fastforms edit' to add email, role, and other details.\n");
+  closeRL();
+}
+
 // ---------------------------------------------------------------------------
 // Route
 // ---------------------------------------------------------------------------
@@ -613,6 +672,9 @@ switch (command) {
   case "init":
     init().catch((e) => { console.error(e.message); process.exit(1); });
     break;
+  case "import":
+    importPersona().catch((e) => { console.error(e.message); process.exit(1); });
+    break;
   case "add":
     addPersona().catch((e) => { console.error(e.message); process.exit(1); });
     break;

package/lib/x402.js

@@ -0,0 +1,112 @@
+const APINOW_BASE = "https://www.apinow.fun/api/v1";
+
+/**
+ * Fetches a Twitter user profile via APINow x402 API.
+ * Requires PRIVATE_KEY env var (Base network wallet with USDC).
+ * Costs $0.01 per call.
+ */
+export async function fetchTwitterProfile(username) {
+  const privateKey = process.env.PRIVATE_KEY;
+  if (!privateKey) {
+    throw new Error(
+      "PRIVATE_KEY not set.\n\n" +
+      "  Twitter import uses x402 micropayments ($0.01 USDC on Base).\n" +
+      "  Set your Base wallet private key:\n\n" +
+      "    export PRIVATE_KEY=0x...\n\n" +
+      "  Or add it to .fastforms/.env or .env"
+    );
+  }
+
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const { createWalletClient, createPublicClient, http } = await import("viem");
+  const { base } = await import("viem/chains");
+  const { x402Client, wrapFetchWithPayment } = await import("@x402/fetch");
+  const { ExactEvmScheme } = await import("@x402/evm/exact/client");
+  const { toClientEvmSigner } = await import("@x402/evm");
+
+  const account = privateKeyToAccount(privateKey);
+
+  const walletClient = createWalletClient({
+    account,
+    chain: base,
+    transport: http("https://mainnet.base.org"),
+  });
+
+  const publicClient = createPublicClient({
+    chain: base,
+    transport: http("https://mainnet.base.org"),
+  });
+
+  const signer = toClientEvmSigner(
+    {
+      address: account.address,
+      signTypedData: (args) => walletClient.signTypedData(args),
+    },
+    {
+      readContract: (args) => publicClient.readContract(args),
+    }
+  );
+
+  const client = new x402Client();
+  const scheme = new ExactEvmScheme(signer);
+  client.register("eip155:8453", scheme);
+
+  const paidFetch = wrapFetchWithPayment(globalThis.fetch, client);
+
+  const url = `${APINOW_BASE}/twit/getUserByUsername?username=${encodeURIComponent(username)}`;
+
+  console.log(`  Fetching @${username} via x402 ($0.01 USDC on Base)...`);
+  console.log(`  Wallet: ${account.address}`);
+
+  const res = await paidFetch(url, {
+    headers: { "x-wallet-address": account.address },
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Twitter API returned ${res.status}: ${body.slice(0, 200)}`);
+  }
+
+  const data = await res.json();
+  return data;
+}
+
+/**
+ * Maps raw Twitter API response to a fastforms user persona.
+ */
+export function twitterToPersona(data, username) {
+  const user = data?.data || data?.user || data;
+
+  const name = user.username || username;
+  const fullName = user.name || "";
+  const bio = user.description || "";
+  const location = user.location || "";
+
+  let website = "";
+  if (user.entities?.url?.urls?.[0]?.expanded_url) {
+    website = user.entities.url.urls[0].expanded_url;
+  } else if (user.url) {
+    website = user.url;
+  }
+
+  const metrics = user.public_metrics || {};
+
+  const facts = {};
+  facts["x handle"] = `@${name}`;
+  if (metrics.followers_count) facts["twitter followers"] = String(metrics.followers_count);
+  if (metrics.tweet_count) facts["tweet count"] = String(metrics.tweet_count);
+  if (user.profile_image_url) facts["avatar"] = user.profile_image_url.replace("_normal", "");
+
+  return {
+    name,
+    fullName,
+    email: "",
+    role: "",
+    location,
+    linkedIn: "",
+    github: "",
+    bio,
+    portfolio: website,
+    facts,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1dolinski/fastforms",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Fill any form fast. Manage personas on the web, fill forms from your terminal.",
   "type": "module",
   "bin": {
@@ -13,6 +13,9 @@
     "README.md"
   ],
   "dependencies": {
+    "@x402/evm": "^2.6.0",
+    "@x402/fetch": "^2.6.0",
+    "viem": "^2.47.4",
     "ws": "^8.18.0"
   },
   "engines": {
@@ -28,6 +31,8 @@
     "automation",
     "chrome",
     "cdp",
-    "personas"
+    "personas",
+    "x402",
+    "twitter"
   ]
 }