officerdev/platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

apify tool, tools API + automation UI, integrations config, super admin restrictions

Browse Source 
- apify tool: TOOL.md definition, index.ts implementation with auto-auth via OFFICER_APIFY_TOKEN, output_path for large datasets
- tools API: /tools routes (list, detail, chat, create, delete) mirroring tasks pattern
- automation UI: tools tab in sidebar, NewTool component, tool detail view
- apify integration: settings page for enterprise API key config, pi-bridge passes env var to containers
- tiktok-trends task: rewritten as agent instructions using apify tool with output_path, scripted report generation for 50KB read limit
- restrict edit/delete of native/global capabilities to Super Admin only (backend + frontend)
- tools authoring guide: TOOLS.md with full spec for TOOL.md frontmatter, index.ts execute signature, patterns

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
pastilhas
2026-03-02 20:00:45 +00:00
co-authored by Claude Opus 4.6
parent 776738a983
commit bd362dc586
19 changed files with 1059 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files
seed/tasks/tiktok-trends/TASK.md
+142 -129
View File
@@ -1,7 +1,7 @@
---
name: TikTok Trends
description: Fetch top trending TikTok videos for a given country and generate an engagement report with optional video downloads.
version: 2
version: 3
author: pastilhas
tags:
- social-media
@@ -9,17 +9,9 @@ tags:
- trends
- apify
- content-analysis
skills:
- Apify
tools:
- apify
dependencies:
- name: tiktok-trends-script
description: The main script at $OFFICER_USER_ROOT/../resources/scripts/apify/tiktok-trends.ts
check_command: test -f "$OFFICER_USER_ROOT/../resources/scripts/apify/tiktok-trends.ts"
optional: false
- name: bun
description: Required to run the TypeScript script
check_command: bun --version
optional: false
- name: yt-dlp
description: Required only when download option is enabled. Downloads TikTok videos.
check_command: yt-dlp --version
@@ -103,26 +95,15 @@ inputs:
type: boolean
default: false
required: false
- name: api_token
description: Apify API token with access to actors. Get yours at https://console.apify.com/account/integrations
type: string
required: true
sensitive: true
outputs:
- name: engagement_report
description: Markdown report with trending videos analysis, engagement metrics, top hashtags, sounds, and creators.
path: tiktok_trends_<country>_<timestamp>/report-YYYY-MM-DD.md
path: tiktok_trends_<country>_<timestamp>/report.md
- name: raw_data
description: Raw JSON data from Apify actor containing all video metadata.
path: tiktok_trends_<country>_<timestamp>/raw-YYYY-MM-DD.json
- name: execution_log
description: Complete script execution log with stdout and stderr for debugging.
path: tiktok_trends_<country>_<timestamp>/run.log
- name: summary
description: Human-readable summary of the run including cost analysis and file listing.
path: tiktok_trends_<country>_<timestamp>/report.md
path: tiktok_trends_<country>_<timestamp>/raw.json
- name: videos
description: Downloaded video files with metadata (only present if download option was enabled).
description: Downloaded video files (only present if download option was enabled).
path: tiktok_trends_<country>_<timestamp>/videos/
optional: true
config:
@@ -134,125 +115,157 @@ config:
Fetch top trending TikTok videos for a given country and generate a comprehensive engagement report.
## Overview
## Important
This task uses the Apify `novi~fast-tiktok-scraper` actor to fetch trending videos from TikTok for a specified country. It generates:
- **Engagement metrics** (total/average views, likes, shares, comments)
- **Top hashtags** found in trending content
- **Popular sounds** being used
- **Creator analysis** (who appears multiple times in trending)
- **Complete video list** with links and stats
- Use the `apify` tool to fetch data. Do NOT call the Apify REST API directly via curl or fetch.
- Do NOT explore or list files before starting. Create the output directory, call the tool, process results.
- If `download` is false (default), do NOT attempt to download any videos.
- Large data files (like `raw.json`) exceed the 50KB read limit. Never try to read them directly. Instead, write a Node.js script to process and transform the data, execute it, then delete the script.
Optionally downloads videos using yt-dlp for offline analysis.
## Steps
## Pre-execution Checks
### 1. Setup output directory
1. **Validate inputs**:
- `api_token` must be provided (required)
- `country` must be a valid 2-letter country code
- `limit` must be between 1-100
2. **Check dependencies**:
- Verify script exists at `$OFFICER_USER_ROOT/../resources/scripts/apify/tiktok-trends.ts`
- Verify bun is installed
- If `download=true`, verify yt-dlp is installed
3. **Test Apify token**:
- Make a test call to `GET https://api.apify.com/v2/users/me` to validate the token
- Abort with clear error if token is invalid or account has no credits
## Execution
Run the script with the following command:
```bash
bun "$OFFICER_USER_ROOT/../resources/scripts/apify/tiktok-trends.ts" \
--apikey "<api_token>" \
--country "<country>" \
--limit <limit> \
--output "<output_dir>" \
<download_flag>
Create a timestamped output directory:
```
$HOME/tiktok-trends/tiktok_trends_<country>_<YYYYMMDD_HHMMSS>/
```
Where:
- `<download_flag>` is `--download` if `download=true`, otherwise omitted
- `<output_dir>` is a timestamped directory created inside `$HOME/tiktok-trends/` (the logged-in user's home directory)
### 2. Fetch trending videos
**Pipe output to log**:
```bash
<command_above> 2>&1 | tee "<output_dir>/run.log"
Call the `apify` tool with `output_path` pointing to `raw.json` in the output directory:
```
apify(
actor_id: "novi~fast-tiktok-scraper",
input: { "type": "TREND", "region": "<country>", "maxItems": <limit> },
output_path: "<output_dir>/raw.json"
)
```
## Success Criteria
The tool saves the full dataset to `raw.json` and returns a summary (item count). If it returns an error or 0 items, report the error and stop.
The task is considered successful when:
- Script exits with code 0
- `report-YYYY-MM-DD.md` exists and is non-empty
- `raw-YYYY-MM-DD.json` exists and contains valid JSON array
- (If download enabled) `videos/` directory exists with at least one file
### 3. Generate engagement report
**Important:** The raw JSON file is too large to read directly (exceeds the 50KB read limit). Instead, write a Node.js script (e.g. `generate-report.js`) in the output directory that reads `raw.json`, processes the data, and writes `report.md`. Then execute it with `node generate-report.js`. Delete the script after it runs successfully.
The script should read `raw.json`, parse it as a JSON array of video items, and write `report.md` with the following sections:
#### Header
```markdown
# TikTok Trending Report — <COUNTRY> — YYYY-MM-DD
Total videos analyzed: <count>
```
#### Engagement Summary
Build a table from each video's `statistics` object (`play_count`, `digg_count`, `share_count`, `comment_count`):
| Metric | Total | Avg per video |
|--------|------:|-------------:|
| Views | ... | ... |
| Likes | ... | ... |
| Shares | ... | ... |
| Comments | ... | ... |
#### Top Hashtags (up to 20)
Extract hashtags from each video's `text_extra` array (entries where `hashtag_name` is set). If `text_extra` is empty, fall back to parsing `#tags` from the `desc` field. Count occurrences, sort descending.
| Hashtag | Count |
|---------|------:|
#### Top Sounds (up to 10)
From each video's `music` object, format as `title — author`. Count occurrences, sort descending.
| Sound | Count |
|-------|------:|
#### Creators Appearing in Trending (up to 10)
From each video's `author.unique_id`. Count occurrences, sort descending.
| Creator | Videos |
|---------|-------:|
#### Video List
Full table of all videos, sorted by position:
| # | Creator | Description | Views | Likes | URL |
|--:|---------|-------------|------:|------:|-----|
- Creator: `@author.unique_id`
- Description: first 60 chars of `desc`, pipe and newline characters replaced, with `...` if truncated
- URL: `share_url`
- Format numbers with locale separators (e.g. `1,234,567`)
### 4. Download videos (only if `download` is true)
If `download` is false, skip this step entirely.
If `download` is true:
1. Check that `yt-dlp` is installed
2. Create a `videos/` subdirectory in the output directory
3. Write all `share_url` values to a `urls.txt` file
4. Run: `yt-dlp -a urls.txt -o "videos/%(id)s.%(ext)s" --write-info-json --no-overwrites`
5. Report how many videos were downloaded. Partial failures are acceptable — do not fail the task if some downloads fail.
### 5. Report results
Print a summary to the user:
- Country and date
- Number of videos fetched
- Top video: `@creator` — views count — URL
- Top hashtag and count
- Output directory path
- Files created and their sizes
## Data Shape Reference
Each video item from the actor has this structure:
```json
{
"aweme_id": "string",
"desc": "video description with #hashtags",
"create_time": 1234567890,
"share_url": "https://www.tiktok.com/@user/video/123",
"author": {
"unique_id": "username",
"nickname": "Display Name",
"uid": "123"
},
"statistics": {
"play_count": 1000000,
"digg_count": 50000,
"share_count": 5000,
"comment_count": 2000,
"collect_count": 1000,
"download_count": 500
},
"music": {
"title": "Sound Name",
"author": "Sound Author"
},
"text_extra": [
{ "hashtag_name": "trending", "type": 1 }
]
}
```
## Error Handling
| Scenario | Action |
|----------|--------|
| Script exits non-zero | Check `run.log` for Apify/API errors. Common causes: invalid token, no credits, rate limits |
| Empty results | Report "No trending videos found" but mark as success if files were created |
| Partial results | Report success if at least 1 video returned, note the discrepancy |
| Timeout (>10 min) | Kill process, report timeout. Check Apify actor status in console |
| Download failures | Report which videos failed but mark task as success if main report generated |
## Post-execution
After successful execution:
1. **Verify outputs**:
- Check all expected files exist
- Validate JSON is parseable
- If download enabled, count video files
2. **Generate summary** (`report.md`):
```markdown
# TikTok Trends Run Summary
## Run Details
- **Date**: YYYY-MM-DD
- **Timestamp**: HH:MM:SS
- **Apify Actor**: novi~fast-tiktok-scraper
- **Country**: <country_name> (<country_code>)
- **Requested**: <limit> videos
- **Received**: <actual_count> videos
- **Duration**: <X> minutes <Y> seconds
## Cost Analysis
- **Apify Credits Used**: <cost> USD
- **Cost per Video**: $<cost/actual_count>
## Key Findings
- **Top Video**: @<creator> - <views> views
<description_preview>
URL: <url>
- **Top Hashtag**: #<hashtag> (<count> occurrences)
- **Top Sound**: <sound_name> (<count> uses)
## Output Files
- `report-YYYY-MM-DD.md` (<size>) - Engagement report
- `raw-YYYY-MM-DD.json` (<size>) - Raw API data
- `run.log` (<size>) - Execution log
- `videos/` (<count> files, <total_size>) - Downloaded videos (if enabled)
## Notes
- <any_warnings_or_errors_from_log>
```
3. **Cleanup**:
- Remove temporary files if any
- Report final status to user
| Apify tool returns error | Report the error message. Common causes: invalid token, no credits, rate limits |
| Empty results | Report "No trending videos found for <country>" and stop |
| Partial results (fewer than requested) | Proceed normally, note the discrepancy in the summary |
| yt-dlp not installed when download=true | Report that yt-dlp is required and skip downloads |
| Download failures | Report which videos failed but do not fail the task |
## Notes
- **Rate limiting**: The Apify actor may take 1-3 minutes depending on the limit
- **Costs**: Each run uses Apify compute units. Monitor usage at https://console.apify.com/billing
- **Data freshness**: Trends data is near real-time but may have slight delays
- **Video downloads**: Downloading many videos can take significant time and storage
- **Country availability**: Not all countries have sufficient trending data; some may return fewer results than requested
- The Apify actor may take 1-3 minutes depending on the limit
- Each run uses Apify compute units — monitor at https://console.apify.com/billing
- Not all countries have sufficient trending data; some may return fewer results than requested