ProductClank — Community-Powered Growth

Community-powered growth for builders. Boost amplifies your social posts with authentic community engagement (replies, likes, reposts). Discover finds relevant conversations and generates AI-powered replies at scale. Use Boost when the user has a post URL. Use Discover when the user wants to find and engage in conversations about their product.

# ProductClank — Community-Powered Growth for Builders

Turn your community into a growth engine. Launch campaigns where real people amplify your product across social platforms — authentic engagement, not bots.

Supports Twitter/X, Instagram, TikTok, LinkedIn, Reddit, and Farcaster.

## Capability 1: Boost

**Amplify a specific social post with community-powered engagement.**

Use Boost when the user has a post URL they want to amplify. One API call, instant results. Works across platforms — just pass the URL.

### Supported Platforms

| Platform | Replies | Likes | Reposts |
|----------|---------|-------|---------|
| Twitter/X | Yes | Yes | Yes |
| Instagram | Yes | Yes | — |
| TikTok | Yes | Yes | — |
| LinkedIn | Yes | Yes | — |
| Reddit | Yes | Yes | — |
| Farcaster | Yes | Yes | Yes |

### How It Works
1. Provide a post URL from any supported platform
2. Platform is auto-detected from the URL
3. Choose action: replies, likes, or reposts (availability varies by platform)
4. Community members execute from their personal accounts
5. You get authentic, third-party engagement

### Pricing

| Action | What You Get | Credits |
|--------|-------------|---------|
| Replies | 10 AI-generated reply threads | 200 |
| Likes | 30 community likes | 300 |
| Reposts | 10 community reposts | 300 |

### API

```
POST /api/v1/agents/campaigns/boost
```

```json
{
  "post_url": "https://x.com/user/status/123456",
  "product_id": "product-uuid",
  "action_type": "replies",
  "reply_guidelines": "optional custom instructions",
  "post_text": "optional — pass post text to skip server-side fetch",
  "post_author": "optional — post author username (used with post_text)"
}
```

> `tweet_url`, `tweet_text`, and `tweet_author` are still accepted for backward compatibility.

**Response:**
```json
{
  "success": true,
  "campaign": {
    "id": "uuid",
    "campaign_number": "CP-042",
    "platform": "twitter",
    "url": "https://app.productclank.com/communiply/uuid"
  },
  "post": {
    "id": "123456789",
    "url": "https://x.com/user/status/123456789",
    "text": "Post content...",
    "author": "username",
    "platform": "twitter"
  },
  "items_generated": 10,
  "credits": {
    "credits_used": 200,
    "credits_remaining": 100
  }
}
```

**Consolidation:** All boost actions for the same product share one campaign. Boosting again adds to the existing campaign (`is_reboost: true`).

### When to Use Boost
- "Boost this post" / "get engagement on my announcement"
- "Get community replies on my LinkedIn post"
- "Get likes on my tweet" / "get reposts on my cast"
- User shares a post URL from any platform and wants community engagement
- Launch announcements, product updates, partnership posts — any post you want your community to rally behind

### How to Run a Boost (Agent Interaction Guide)

1. **Get the post URL** — ask the user for their post URL (the post they want community to engage with). Any supported platform works.
2. **Choose action type** — ask: "How should the community engage? Replies (support, questions, congrats), likes, or reposts?" Default to replies if unclear. Note: reposts only available on Twitter and Farcaster.
3. **Find the product** — search `GET /agents/products/search?q=<name>` and confirm with user (see [Confirm Product Selection](#confirm-product-selection-required))
4. **Get reply guidelines** (for replies) — ask what kind of engagement they want: "Should community replies congratulate the team? Ask about features? Show excitement?" Use this to set `reply_guidelines`
5. **Confirm cost** — "This will use 200 credits for 10 community replies. Proceed?"
6. **Execute** — `POST /agents/campaigns/boost`
7. **Share results** — show campaign URL and credits remaining

### Complete Boost Example

```typescript
// User says: "Get my community to engage with my latest announcement"
const API = "https://app.productclank.com/api/v1/agents";
const headers = {
  "Authorization": `Bearer ${process.env.PRODUCTCLANK_API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Search for the product
const search = await fetch(`${API}/products/search?q=MyProduct&limit=5`, { headers });
const { products } = await search.json();
// → Confirm with user: "I found MyProduct. Is this correct?"

// 2. Boost a Twitter post
const res = await fetch(`${API}/campaigns/boost`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    post_url: "https://x.com/myproduct/status/123456789",
    product_id: products[0].id,
    action_type: "replies",
    reply_guidelines: "Show genuine excitement about the launch. Ask thoughtful questions about the new features or congratulate the team. Keep it authentic — no sales pitch.",
    post_text: "We just shipped v2.0! New API with 10x faster response times, batch endpoints, and webhook support. Try it out →", // optional, skips server fetch
    post_author: "myproduct", // optional, used with post_text
  }),
});

const result = await res.json();

if (result.success) {
  console.log(`✅ Boosted on ${result.campaign.platform}! ${result.items_generated} community replies generated`);
  console.log(`📊 Dashboard: ${result.campaign.url}`);
  console.log(`💰 Credits remaining: ${result.credits.credits_remaining}`);
}

// 3. Works with any platform — just change the URL
await fetch(`${API}/campaigns/boost`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    post_url: "https://www.linkedin.com/posts/myproduct-launch-update-123",
    product_id: products[0].id,
    action_type: "replies",
    post_text: "Excited to announce our Series A! ...", // recommended for non-Twitter platforms
  }),
});
```

### CLI

```bash
# Boost a Twitter post
communiply boost https://x.com/myproduct/status/123 --action replies \
  --guidelines "Congratulate the team, ask about new features, show excitement"

# Boost a LinkedIn post
communiply boost https://linkedin.com/posts/myproduct-update-123 --action likes

# Boost a TikTok video
communiply boost https://tiktok.com/@myproduct/video/123 --action replies

# Boost a Farcaster cast
communiply boost https://warpcast.com/myproduct/0xabc123 --action reposts
```

### Post Text Resolution
For **replies**, post text is required for AI generation. Resolution order:
1. Client-provided `post_text` (skips fetch — recommended for non-Twitter platforms)
2. Server-side fetch via platform API (Twitter oEmbed, TikTok oEmbed, Reddit JSON, etc.)
3. If text unavailable, returns `503` for replies. Likes/reposts work without text.

---

## Capability 2: Discover

**Find relevant Twitter conversations and generate AI-powered replies at scale.**

Use Discover when the user wants to proactively find and engage in conversations about their product's topic. This is a multi-step flow — more powerful than Boost, but requires more setup.

### How It Works
1. Define keywords and target audience
2. AI discovers relevant conversations on Twitter
3. AI generates contextual replies for each opportunity
4. Community members claim replies and post from personal accounts
5. Track results in real-time

### Pricing

| Operation | Credits |
|-----------|---------|
| Campaign creation | 10 |
| Post discovery + reply generation | 12 per post |
| Reply regeneration | 5 per reply |
| Research analysis | Free |

### API Flow

**Step 1: Create campaign (10 credits)**
```
POST /api/v1/agents/campaigns
```

```json
{
  "product_id": "product-uuid",
  "title": "Launch Week Buzz",
  "keywords": ["AI tools", "productivity apps", "workflow automation"],
  "search_context": "People discussing AI productivity tools and looking for better solutions",
  "mention_accounts": ["@myproduct"],
  "reply_style_tags": ["friendly", "helpful"],
  "reply_length": "short",
  "reply_posted_by": "community",
  "min_follower_count": 500,
  "max_post_age_days": 7
}
```

**Step 2 (optional): Run research (free)**
```
POST /api/v1/agents/campaigns/{id}/research
```
Expands keywords, discovers influencers, finds Twitter lists. Results are automatically used in Step 3.

**Step 3: Ge