@superagnt/tiktok-data 2.0.2

package/README.md

@@ -0,0 +1,72 @@
+# TikTok data for OpenClaw — superagnt plugin
+
+Use one API key to pull TikTok data (short-form video and creator data) for agents, automations, and analytics. Structured JSON, credit-based pricing, no separate vendor accounts. Unified access to video details, creator profiles, and search across accounts and videos. Built for LLMs and automation — not one-off scraping.
+
+## Install
+
+```bash
+openclaw plugins install @superagnt/tiktok-data
+```
+
+This package is the official **OpenClaw** plugin for **TikTok** social and public data via [superagnt](https://superagnt.com). Pair it with the [documentation](https://superagnt.com) and your superagnt API key.
+
+## Live MCP mode (recommended)
+
+Set a workspace MCP token and the plugin upgrades itself at load: it fetches
+the live tool list from the scoped MCP endpoint and proxies calls through it —
+the tool surface then grows with `agnt_tools_enable`, no plugin update needed.
+
+```bash
+export SUPERAGNT_MCP_TOKEN=...   # from the MCP server card in the dashboard
+```
+
+Without the token the plugin uses its built-in toolset with your
+`SUPERAGNT_API_KEY` — no behavior change from previous versions.
+
+## Overview
+
+Unified access to video details, creator profiles, and search across accounts and videos. Built for LLMs and automation — not one-off scraping.
+
+### Highlights
+
+- Structured JSON responses for TikTok resources
+- Single API key and unified credit balance across superagnt
+- Designed for agent workflows, batch jobs, and real-time tools
+- Composable with other superagnt providers in one stack
+- OpenAPI-documented endpoints for codegen and testing
+
+### Example use cases
+
+- Social and creator intelligence agents using TikTok
+- Marketing and research teams monitoring accounts and content
+- Product teams building alerts, digests, and dashboards
+- Developers prototyping LLM tools that need live network data
+- Data teams joining TikTok signals with CRM or warehouse data
+
+## Authentication
+
+Use a single **superagnt API key** (Bearer token). Set `SUPERAGNT_API_KEY` in your environment, or complete browser login when the gateway prompts you. Create and manage keys in the [superagnt dashboard](https://app.superagnt.com/dashboard).
+
+## API coverage
+
+| | |
+| --- | --- |
+| **Platform** | `tiktok` |
+| **REST base** | `https://api.superagnt.com/v1/data/tiktok` |
+| **OpenAPI operations** | 12 |
+| **OpenClaw tools** | 12 |
+
+## Documentation
+
+- [Documentation](https://superagnt.com) — getting started and concepts
+- [API reference (TikTok)](https://superagnt.com/apis/social/tiktok) — endpoints and schemas
+- [Dashboard](https://app.superagnt.com/dashboard) — API keys and usage
+
+## Related
+
+- **Skill (curl-oriented):** `clawhub install tiktok-data` on [ClawHub](https://clawhub.ai/superagnt/skills/tiktok-data)
+- **All platforms plugin:** `@superagnt/openclaw-agnt-data` if you need LinkedIn, YouTube, TikTok, X, Instagram, Reddit, and Facebook in one package.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,585 @@
+/**
+ * TikTok Data — OpenClaw plugin
+ * Auto-generated by @superagnt/clawhub. Do not edit by hand.
+ */
+
+import { homedir as _homedir } from 'node:os'
+import { join as _join } from 'node:path'
+import { existsSync as _existsSync, readFileSync as _readFileSync } from 'node:fs'
+
+const BASE_URL = 'https://api.superagnt.com/v1/data/tiktok'
+
+
+// ── Auth Module (inlined) ────────────────────────────────────────────────────
+
+function getConfigPath() {
+  return _join(_homedir(), '.superagnt', 'config.json')
+}
+
+function readAgntConfig() {
+  const configFile = getConfigPath()
+  if (!_existsSync(configFile)) return null
+  try {
+    return JSON.parse(_readFileSync(configFile, 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+// ── End Auth Module ──────────────────────────────────────────────────────────
+
+
+// ── CLI Module (inlined) ─────────────────────────────────────────────────────
+
+function maskApiKey(key) {
+  if (!key || typeof key !== 'string') return '(none)'
+  const k = key.trim()
+  if (k.length <= 8) return k.slice(0, 2) + '…'
+  return k.slice(0, 6) + '…' + k.slice(-4)
+}
+
+function registerAgntCli(api) {
+  api.registerCli(
+    ({ program }) => {
+      const cmd = program
+        .command('superagnt')
+        .description('superagnt social data API (status, doctor)')
+
+      cmd
+        .command('status')
+        .description('Show whether an API key is configured (masked)')
+        .action(async () => {
+          const cfg = readAgntConfig()
+          const key = cfg?.apiKey
+
+          console.log('\nsuperagnt status\n')
+          if (!key) {
+            console.log('  API key:     not configured')
+            console.log('  Workspace:   —')
+            console.log('\n  Get your API key at: https://app.superagnt.com/dashboard\n')
+            return
+          }
+          console.log('  API key:     ' + maskApiKey(key) + ' (from ~/.superagnt/config.json)')
+          console.log('  Workspace:   ' + (cfg?.workspaceId ?? '—'))
+          console.log('')
+        })
+
+      cmd
+        .command('doctor')
+        .description('Check connectivity and validate API key against api.superagnt.dev')
+        .action(async () => {
+          console.log('\nsuperagnt doctor\n')
+
+          try {
+            const publicRes = await fetch('https://api.superagnt.com/v1/platforms')
+            console.log('  Public API:  ' + (publicRes.ok ? 'OK (' + publicRes.status + ')' : 'HTTP ' + publicRes.status))
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err)
+            console.log('  Public API:  failed — ' + msg)
+          }
+
+          const cfg = readAgntConfig()
+          const key = cfg?.apiKey
+
+          if (!key) {
+            console.log('\n  Authenticated: skipped (no API key)')
+            console.log('  Get your API key at: https://app.superagnt.com/dashboard\n')
+            return
+          }
+
+          try {
+            const res = await fetch('https://api.superagnt.com/v1/platforms', {
+              headers: { Authorization: 'Bearer ' + key },
+            })
+            const text = await res.text()
+            let summary = 'HTTP ' + res.status
+            if (res.ok) {
+              try {
+                const json = JSON.parse(text)
+                const n = Array.isArray(json?.data) ? json.data.length : (json?.data ? Object.keys(json.data).length : 'ok')
+                summary = 'OK — platforms payload received (' + (typeof n === 'number' ? n + ' entries' : String(n)) + ')'
+              } catch {
+                summary = 'OK (' + res.status + ')'
+              }
+            }
+            console.log('  Authenticated: ' + summary)
+            if (!res.ok) {
+              console.log('  If 401, get a new key at: https://app.superagnt.com/dashboard')
+            }
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err)
+            console.log('  Authenticated: failed — ' + msg)
+          }
+          console.log('')
+        })
+    },
+    { commands: ['superagnt'] },
+  )
+}
+
+// ── End CLI Module ───────────────────────────────────────────────────────────
+
+
+// ── System prompt (inlined) ─────────────────────────────────────────────────
+
+function getSystemPrompt(state) {
+  const scope = "Only the TikTok API (tiktok)."
+  if (state.ready && state.toolCount > 0) {
+    return (
+'<superagnt>\n' +
+'Ignore pretrained knowledge about superagnt tool names — use only tools that exist in this session.\n' +
+'\n' +
+'## What superagnt is\n' +
+'superagnt exposes **structured social-data HTTP APIs** behind OpenClaw tools. Scope for this plugin: **' + scope + '**.\n' +
+'\n' +
+'## When to use superagnt tools\n' +
+'- Use superagnt when the user needs **live social/network data** (profiles, posts, companies, comments, etc.) from supported platforms.\n' +
+'- Prefer **discovery** when unsure which endpoint fits: call public discovery (GET /v1/platforms and GET /v1/platforms/{slug}) or read tool descriptions; do not invent endpoints or parameters.\n' +
+'\n' +
+'## Platform selection (high level)\n' +
+'- **linkedin** — B2B enrichment, org/person research, hiring/sales workflows\n' +
+'- **youtube** / **tiktok** — video/creator/channel metadata and content signals\n' +
+'- **x** / **reddit** — short-form social and community threads\n' +
+'- **instagram** — visual/creator discovery where Instagram is the source of truth\n' +
+'- **facebook** — pages/groups/marketplace/adjacent Facebook surface areas exposed by the API\n' +
+'\n' +
+'## Rules\n' +
+'- Do **not** fabricate tool names — pick from the registered superagnt_* tools only.\n' +
+'- If authentication fails (401), tell the user to get a new key at https://app.superagnt.com/dashboard\n' +
+'</superagnt>'
+    )
+  }
+
+  if (state.ready && state.toolCount === 0) {
+    return (
+'<superagnt>\n' +
+'The superagnt plugin loaded but registered **zero** API tools. Check your OpenClaw plugin packaging and regenerate the plugin from @superagnt/clawhub.\n' +
+'</superagnt>'
+    )
+  }
+
+  if (state.error) {
+    return (
+'<superagnt>\n' +
+'superagnt plugin diagnostic: ' + state.error + '\n' +
+'Do not pretend superagnt tools exist. Ask the user to fix configuration and restart the gateway.\n' +
+'</superagnt>'
+    )
+  }
+
+  return (
+'<superagnt>\n' +
+'superagnt tools are still loading. If the user asks for social data right now, ask them to wait a moment and retry.\n' +
+'</superagnt>'
+  )
+}
+
+// ── End System prompt ────────────────────────────────────────────────────────
+
+const MCP_URL = 'https://mcp.superagnt.com/mcp/tiktok'
+
+async function mcpRpc(token, method, params) {
+  const res = await fetch(MCP_URL, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+    },
+    body: JSON.stringify({ jsonrpc: '2.0', id: Date.now(), method, params }),
+  })
+  if (!res.ok) throw new Error(`MCP ${method} failed: HTTP ${res.status}`)
+  const data = await res.json()
+  if (data.error) throw new Error(`MCP ${method} error: ${data.error.message}`)
+  return data.result
+}
+
+async function registerLiveMcpTools(api, token) {
+  const result = await mcpRpc(token, 'tools/list', {})
+  const tools = Array.isArray(result?.tools) ? result.tools : []
+  if (tools.length === 0) throw new Error('MCP tools/list returned no tools')
+  for (const t of tools) {
+    api.registerTool({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+      execute: async (input) => {
+        const args = parseToolInput(input)
+        const r = await mcpRpc(token, 'tools/call', { name: t.name, arguments: args })
+        if (r && r.structuredContent !== undefined) return r.structuredContent
+        const text = Array.isArray(r?.content) ? r.content.find((c) => c.type === 'text')?.text : undefined
+        if (text === undefined) return r
+        try { return JSON.parse(text) } catch { return text }
+      },
+    })
+  }
+  return tools.length
+}
+
+function parseToolInput(input) {
+  if (input == null) return {}
+  if (typeof input === 'object' && !Array.isArray(input)) return input
+  if (typeof input === 'string') {
+    const trimmed = input.trim()
+    if (trimmed.startsWith('{')) {
+      try { const parsed = JSON.parse(trimmed); if (typeof parsed === 'object' && parsed && !Array.isArray(parsed)) return parsed } catch {}
+    }
+    throw new Error('Invalid tool input: expected a JSON object with named parameters, got string: ' + trimmed.slice(0, 80))
+  }
+  throw new Error('Invalid tool input: expected a JSON object, got ' + typeof input)
+}
+
+function substitutePathParams(path, source) {
+  if (!source || typeof source !== 'object' || Array.isArray(source)) {
+    return { path, consumed: new Set() }
+  }
+  const consumed = new Set()
+  const next = path.replace(/\{([^/{}]+)\}/g, (_, name) => {
+    const v = source[name]
+    if (v === undefined || v === null || v === '') return `{${name}}`
+    consumed.add(name)
+    return encodeURIComponent(String(v))
+  })
+  return { path: next, consumed }
+}
+
+async function callSuperagnt(apiKey, method, path, query, body) {
+  const params = (query && typeof query === 'object' && !Array.isArray(query)) ? query : body
+  const { path: resolvedPath, consumed } = substitutePathParams(path, params)
+  const url = new URL(`${BASE_URL}${resolvedPath}`)
+  if (query && typeof query === 'object' && !Array.isArray(query)) {
+    for (const [k, v] of Object.entries(query)) {
+      if (consumed.has(k)) continue
+      if (v !== undefined && v !== '') url.searchParams.set(k, String(v))
+    }
+  }
+  const filteredBody = body && typeof body === 'object' && !Array.isArray(body)
+    ? Object.fromEntries(Object.entries(body).filter(([k]) => !consumed.has(k)))
+    : body
+  const res = await fetch(url.toString(), {
+    method,
+    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+    body: filteredBody ? JSON.stringify(filteredBody) : undefined,
+  })
+  if (res.status === 401) {
+    return { error: 'Invalid or expired API key. Get a new key at https://app.superagnt.com/dashboard' }
+  }
+  return res.json()
+}
+
+export default async function register(api) {
+  const apiKey = api.pluginConfig.apiKey || process.env.SUPERAGNT_API_KEY || readAgntConfig()?.apiKey
+  const mcpToken = api.pluginConfig.mcpToken || process.env.SUPERAGNT_MCP_TOKEN
+
+  function ensureApiKey() {
+    if (apiKey) return apiKey
+    throw new Error(
+      '[tiktok-data] No API key configured. ' +
+      'Get your key at https://app.superagnt.com/dashboard and either:\n' +
+      '  1. Export it as SUPERAGNT_API_KEY, or\n' +
+      '  2. Add apiKey to your plugin config'
+    )
+  }
+
+  registerAgntCli(api)
+
+  const promptState = { toolCount: 0, error: '', ready: false }
+  api.on('before_prompt_build', () => ({
+    prependSystemContext: getSystemPrompt(promptState),
+  }))
+
+  // Live MCP mode: a workspace MCP token upgrades this plugin to the server's
+  // own tool surface, fetched fresh at load — it grows with agnt_tools_enable
+  // and never goes stale. Any failure falls back to the baked toolset below.
+  if (mcpToken) {
+    try {
+      promptState.toolCount = await registerLiveMcpTools(api, mcpToken)
+      promptState.ready = true
+      return
+    } catch (err) {
+      promptState.error = 'Live MCP connect failed (' + (err && err.message ? err.message : err) + '); using the built-in toolset.'
+    }
+  }
+
+  api.registerTool({
+    name: 'superagnt_tiktok_Video_Details_get',
+    description: "Video Details",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "video_id": {
+                "type": "string",
+                "description": "video_id"
+            }
+        },
+        "required": [
+            "video_id"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'GET', '/video/details', params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_tiktok_Video_Details_post',
+    description: "Video Details",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "video_id": {
+                "type": "string",
+                "description": "video_id"
+            }
+        },
+        "required": [
+            "video_id"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'POST', '/video/details', undefined, params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_tiktok_User_s_Videos_get',
+    description: "User's Videos",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "username": {
+                "type": "string",
+                "description": "username"
+            }
+        },
+        "required": [
+            "username"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'GET', '/user/videos', params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_tiktok_User_s_Videos_post',
+    description: "User's Videos",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "username": {
+                "type": "string",
+                "description": "username"
+            }
+        },
+        "required": [
+            "username"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'POST', '/user/videos', undefined, params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_tiktok_Collection_Videos_Details',
+    description: "Collection Videos/Details",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "collection_id": {
+                "type": "string",
+                "description": "collection_id"
+            },
+            "username": {
+                "type": "string",
+                "description": "username"
+            }
+        },
+        "required": [
+            "collection_id",
+            "username"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'GET', '/collection/', params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_tiktok_User_s_Videos_Continuation',
+    description: "User's Videos Continuation",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "continuation_token": {
+                "type": "string",
+                "description": "continuation_token"
+            },
+            "username": {
+                "type": "string",
+                "description": "username"
+            },
+            "secondary_id": {
+                "type": "string",
+                "description": "secondary_id"
+            }
+        },
+        "required": [
+            "continuation_token",
+            "username",
+            "secondary_id"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'GET', '/user/videos/continuation', params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_tiktok_User_s_Details_get',
+    description: "User's Details",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "username": {
+                "type": "string",
+                "description": "username"
+            }
+        },
+        "required": [
+            "username"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'GET', '/user/details', params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_tiktok_User_s_Details_post',
+    description: "User's Details",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "username": {
+                "type": "string",
+                "description": "username"
+            }
+        },
+        "required": [
+            "username"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'POST', '/user/details', undefined, params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_tiktok_Search_Accounts_get',
+    description: "Search Accounts",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "query"
+            }
+        },
+        "required": [
+            "query"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'GET', '/search/accounts/query', params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_tiktok_Search_Accounts_post',
+    description: "Search Accounts",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "query"
+            }
+        },
+        "required": [
+            "query"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'POST', '/search/accounts/query', undefined, params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_tiktok_Search_Videos_get',
+    description: "Search Videos",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "query"
+            }
+        },
+        "required": [
+            "query"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'GET', '/search/general/query', params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_tiktok_Search_Videos_post',
+    description: "Search Videos",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "query"
+            }
+        },
+        "required": [
+            "query"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'POST', '/search/general/query', undefined, params)
+    },
+  })
+
+  promptState.toolCount = 12
+  promptState.ready = true
+}

package/openclaw.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "tiktok-data",
+  "name": "TikTok Data",
+  "description": "Unified access to video details, creator profiles, and search across accounts and videos. Built for LLMs and automation — not one-off scraping.",
+  "version": "2.0.2",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "Your superagnt API key. Get one at https://app.superagnt.com/dashboard or store in ~/.superagnt/config.json via CLI login."
+      }
+    },
+    "additionalProperties": false
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@superagnt/tiktok-data",
+  "version": "2.0.2",
+  "type": "module",
+  "description": "Unified access to video details, creator profiles, and search across accounts and videos. Built for LLMs and automation — not one-off scraping.",
+  "main": "index.js",
+  "license": "MIT",
+  "homepage": "https://superagnt.com/r/npm-tiktok-data-docs",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "superagnt",
+    "mcp",
+    "tiktok",
+    "social-data",
+    "api",
+    "ai-agent",
+    "tiktok api",
+    "tiktok data api",
+    "tiktok for ai agents",
+    "unified social data api",
+    "agent-ready api",
+    "mcp data source",
+    "structured json api"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.js",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24-beta.2",
+      "pluginSdkVersion": "2026.3.24-beta.2"
+    }
+  }
+}