twentythree-skills 1.0.0

package/skills/reference/comment.md

@@ -0,0 +1,225 @@
+---
+name: comment
+description: Moderate and manage comments, questions, and chat on videos, categories, and webinars.
+---
+
+# TwentyThree Comment Commands
+
+> List, moderate, and manage comments, questions, and chat messages on TwentyThree content.
+> Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: read (list), write (add, update, delete, promote, clone, set-order, reaction add).
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+> For any flag not listed here, run `twentythree comment <cmd> --agent` to get the complete flag list, types, and defaults.
+
+## Commands
+
+### comment list
+
+**Auth scope:** read  **Side effects:** none  **Output:** table (ID, Author, Content, Type, Date)
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | no | Filter by object ID |
+| `--object-type` | no | Filter by object type (photo, album, live) |
+| `--comment-type` | no | Filter by comment type (comment, question, chat) |
+| `--search` | no | Search comments by content |
+| `--order` | no | Sort order for results |
+| `--include-reactions` | no | Include reactions on each comment |
+| `--include-replies` | no | Include reply-to comments |
+| `--promoted` | no | Filter to promoted comments only |
+
+```bash
+# List all comments in the workspace
+twentythree comment list --json
+
+# List only questions on a specific webinar
+twentythree comment list --object-id <webinar-id> --object-type live --comment-type question --json
+```
+
+### comment add
+
+**Auth scope:** write  **Side effects:** creates  **Output:** none
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | yes | Object ID to comment on |
+| `--object-type` | yes | Object type (photo, album, live) |
+| `--content` | no | Comment text content |
+| `--name` | no | Author name for the comment |
+| `--email` | no | Author email for the comment |
+| `--url` | no | URL associated with the comment |
+| `--comment-type` | no | Comment type (comment, question, chat) |
+| `--reply-to` | no | Comment ID to reply to |
+| `--comment-time` | no | Timestamp for the comment |
+| `--object-token` | no | Object token for the target object |
+
+```bash
+# Add a comment to a video
+twentythree comment add --object-id <video-id> --object-type photo --content "Great video!" --json
+
+# Add a question to a webinar chat
+twentythree comment add --object-id <webinar-id> --object-type live --content "What is next?" --comment-type question --json
+```
+
+### comment update
+
+**Auth scope:** write  **Side effects:** updates  **Output:** none
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | yes | Object ID the comment belongs to |
+| `--status` | no | Comment status (answered, dismissed, or empty to clear) |
+
+```bash
+# Mark a question as answered
+twentythree comment update <comment-id> --object-id <webinar-id> --status answered --json
+
+# Dismiss an inappropriate comment
+twentythree comment update <comment-id> --object-id <video-id> --status dismissed --json
+```
+
+### comment delete
+
+**Auth scope:** write  **Side effects:** destructive  **Output:** none
+
+Takes `<comment-id>` as positional argument. No additional flags.
+
+```bash
+# Delete a comment
+twentythree comment delete <comment-id> --json
+
+# Delete a question from a webinar
+twentythree comment delete <comment-id> --json
+```
+
+### comment promote
+
+**Auth scope:** write  **Side effects:** updates  **Output:** none
+
+Takes `<comment-id>` as positional argument. Toggles promoted status if `--promoted` is omitted.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--promoted` | no | Set promoted status explicitly (omit to toggle) |
+
+```bash
+# Promote a comment (toggle on)
+twentythree comment promote <comment-id> --json
+
+# Explicitly set promoted status to true
+twentythree comment promote <comment-id> --promoted --json
+```
+
+### comment clone
+
+**Auth scope:** write  **Side effects:** creates  **Output:** none
+
+Takes `<comment-id>` as positional argument. Clones the comment, optionally changing its type.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--clone-type` | no | Type for the cloned comment (chat, question, comment) |
+
+```bash
+# Clone a comment as-is
+twentythree comment clone <comment-id> --json
+
+# Clone a comment and set it as a question type
+twentythree comment clone <comment-id> --clone-type question --json
+```
+
+### comment set-order
+
+**Auth scope:** write  **Side effects:** updates  **Output:** none
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | yes | Object ID whose comments are being reordered |
+| `--order` | yes | Comma-separated list of comment IDs in desired display order |
+| `--comment-type` | no | Comment type to reorder (default: question) |
+
+```bash
+# Reorder questions on a webinar
+twentythree comment set-order --object-id <webinar-id> --order "<id1>,<id2>,<id3>" --json
+
+# Reorder only chat-type comments
+twentythree comment set-order --object-id <webinar-id> --order "<id1>,<id2>" --comment-type chat --json
+```
+
+## Subtopic: comment reaction
+
+### comment reaction add
+
+**Auth scope:** write  **Side effects:** creates  **Output:** none
+
+Takes `<comment-id>` as positional argument.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--reaction` | yes | Reaction emoji to add |
+| `--object-id` | yes | Object ID the comment belongs to |
+| `--object-token` | yes | Object token for the target object |
+| `--object-type` | no | Object type (live, photo, album) |
+| `--uuid` | no | UUID identifier |
+
+```bash
+# Add a thumbs-up reaction to a comment
+twentythree comment reaction add <comment-id> --object-id <webinar-id> --object-token <token> --reaction "👍" --json
+
+# Add a heart reaction to a video comment
+twentythree comment reaction add <comment-id> --object-id <video-id> --object-token <token> --reaction "❤️" --object-type photo --json
+```
+
+## Common Patterns
+
+### Moderate webinar Q&A session
+
+```bash
+# List all questions from a webinar
+twentythree comment list --object-id <webinar-id> --object-type live --comment-type question --json
+
+# Promote an important question for visibility
+twentythree comment promote <question-id> --json
+
+# Mark a question as answered after responding
+twentythree comment update <question-id> --object-id <webinar-id> --status answered --json
+```
+
+### Reorder promoted questions for display
+
+```bash
+# Step 1: List promoted questions to get their IDs
+twentythree comment list --object-id <webinar-id> --object-type live --comment-type question --promoted --json
+
+# Step 2: Set the display order using captured IDs
+twentythree comment set-order --object-id <webinar-id> --order "<id1>,<id2>,<id3>" --comment-type question --json
+```
+
+## Terminology Notes
+
+The `--object-type` flag uses the legacy API object names:
+- pass `photo` for a video
+- pass `album` for a category
+- pass `live` for a webinar
+
+This is the only place in the `comment` topic where terminology diverges from CLI naming.
+The `api_endpoint` field in `--agent` output also uses these legacy names (e.g. `GET /comment/list`).

package/skills/reference/openupload.md

@@ -0,0 +1,138 @@
+---
+name: openupload
+description: Third-party upload tokens — allow anonymous users to upload files using a pre-issued token.
+---
+
+# TwentyThree Open Upload Commands
+
+> Issue tokens that let third parties upload files without full API credentials.
+> The chunked upload engine handles large files automatically — never construct multipart requests directly.
+> Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: read (list), write (upload-file, update-file).
+`upload-file` and `update-file` additionally require `--token-upload-id` and `--token` values
+provided by the workspace admin who issued the token.
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+> For any flag not listed here, run `twentythree openupload <cmd> --agent` to get the complete flag list, types, and defaults.
+
+## Commands
+
+### openupload list
+
+**Auth scope:** read  **Side effects:** none  **Output:** table (ID, Name, Token, Public)
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--token-upload-id` | no | Filter by open upload token upload ID |
+| `--token` | no | Filter by open upload token value |
+| `--app` | no | Filter by app open uploads (boolean) |
+
+```bash
+# List all open upload tokens in the workspace
+twentythree openupload list --json
+
+# Filter to a specific token upload
+twentythree openupload list --token-upload-id 123 --json
+```
+
+### openupload upload-file
+
+**Auth scope:** write  **Side effects:** creates  **Output:** key-value
+
+> **Memory rule:** Always use chunked upload for file uploads. This command handles chunking
+> automatically — never construct multipart requests directly.
+
+The returned `upload-key` identifies the uploaded file and is required for subsequent metadata
+updates via `openupload update-file`.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--file-path` | yes | Path to the file to upload |
+| `--token-upload-id` | yes | Open upload token upload ID (provided by workspace admin) |
+| `--token` | yes | Open upload token (provided by workspace admin) |
+| `--chunk-size` | no | Chunk size in bytes (default: 5242880) |
+| `--concurrency` | no | Parallel chunk uploads (default: 5) |
+
+```bash
+# Upload a video file using a token
+twentythree openupload upload-file --file-path ./video.mp4 \
+  --token-upload-id <id> --token <tok> --json
+
+# Upload with custom chunk size for a slow connection
+twentythree openupload upload-file --file-path ./recording.mp4 \
+  --token-upload-id <id> --token <tok> --chunk-size 2097152 --json
+```
+
+### openupload update-file
+
+**Auth scope:** write  **Side effects:** updates  **Output:** key-value
+
+Updates metadata for an already-uploaded file. Requires the `--upload-key` returned by `upload-file`.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--token-upload-id` | yes | Open upload token upload ID |
+| `--token` | yes | Open upload token |
+| `--upload-key` | yes | Upload key identifying the uploaded file |
+| `--title` | no | New title for the uploaded file |
+| `--description` | no | New description for the uploaded file |
+| `--tags` | no | Tags for the uploaded file (space-separated) |
+
+```bash
+# Set title and description after upload
+twentythree openupload update-file \
+  --token-upload-id <id> --token <tok> --upload-key <key> \
+  --title "Product Demo" --description "Q2 launch demo" --json
+
+# Set tags on the uploaded file
+twentythree openupload update-file \
+  --token-upload-id <id> --token <tok> --upload-key <key> \
+  --tags "demo product q2" --json
+```
+
+## Common Patterns
+
+### Full third-party upload workflow
+
+```bash
+# Step 1: Workspace admin shares token-upload-id and token out-of-band with the third party.
+# The third party runs:
+
+# Step 2: Upload the file (chunking is automatic)
+twentythree openupload upload-file \
+  --file-path ./presentation.mp4 \
+  --token-upload-id <token-upload-id> \
+  --token <token> \
+  --json
+# => Returns { upload_key: "<key>", ... }
+# Capture: upload_key for the next step
+
+# Step 3: Set metadata on the uploaded file
+twentythree openupload update-file \
+  --token-upload-id <token-upload-id> \
+  --token <token> \
+  --upload-key <key> \
+  --title "Partner Submission" \
+  --tags "partner external" \
+  --json
+```
+
+### Verify uploaded files as workspace admin
+
+```bash
+# List all open uploads to review received files
+twentythree openupload list --json
+
+# Filter to a specific token upload ID
+twentythree openupload list --token-upload-id <token-upload-id> --json
+```

package/skills/reference/player.md

@@ -0,0 +1,192 @@
+---
+name: player
+description: List and configure TwentyThree embed players, generate embed HTML, and discover available styles.
+---
+
+# TwentyThree Player Commands
+
+> List and update embed players, generate embed code for videos/webinars/categories, and
+> discover available player styles and embed versions.
+> Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: anonymous (embed), read (list, embed-versions, styles), write (update, delete).
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+> For any flag not listed here, run `twentythree player <cmd> --agent` to get the complete flag list, types, and defaults.
+
+## Commands
+
+### player list
+
+**Auth scope:** read  **Side effects:** none  **Output:** table (ID, Name, Default)
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--source` | no | Analytics source tag to filter by |
+
+```bash
+# List all players in the workspace
+twentythree player list --json
+
+# List players tagged with a specific analytics source
+twentythree player list --source embed --json
+```
+
+### player update
+
+**Auth scope:** write  **Side effects:** updates  **Output:** none
+
+Takes `<player-id>` as positional argument.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--name` | no | New name for the player |
+| `--description` | no | New description for the player |
+| `--data` | no | JSON-encoded player properties to merge into the request body |
+
+```bash
+# Rename a player
+twentythree player update 42 --name "Brand Player v2" --json
+
+# Update a player with custom data properties
+twentythree player update 42 --name "Campaign Player" --description "Q2 campaign" --json
+```
+
+### player delete
+
+**Auth scope:** write  **Side effects:** destructive  **Output:** none
+
+Takes `<player-id>` as positional argument. No flags.
+
+```bash
+# Delete a player by ID
+twentythree player delete 42 --json
+
+# List players first to confirm the ID before deletion
+twentythree player list --json
+twentythree player delete 42 --json
+```
+
+### player embed
+
+**Auth scope:** anonymous  **Side effects:** none  **Output:** key-value (HTML embed code)
+
+Generates embed HTML for a video, webinar, or category. Because this command returns HTML,
+redirecting to a file is more practical than `--json` for most uses.
+
+**Exception:** `player embed` outputs HTML. Use redirect (`> embed.html`) to save output to a file.
+Use `--json` only when capturing the raw embed code string in a structured response.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--video-id` | no | Video ID to embed (maps to photo_id in API) |
+| `--webinar-id` | no | Webinar ID to embed (maps to live_id in API) |
+| `--category-id` | no | Category ID to embed (maps to album_id in API) |
+| `--player-id` | no | Player ID to use (default: workspace default player) |
+| `--url` | no | Workspace URL to resolve to an embed code |
+| `--width` | no | Desired embed width in pixels |
+| `--height` | no | Desired embed height in pixels |
+| `--responsive` | no | Return a responsive embed code |
+| `--autoplay` | no | Enable auto-play in the embed code |
+| `--iframe` | no | Return an iframe-based embed code |
+| `--start` | no | Start position in seconds |
+| `--include-unpublished` | no | Include unpublished content in player parameters |
+| `--token` | no | Video token for private or token-protected videos |
+| `--source` | no | Analytics source tag |
+
+```bash
+# Generate embed HTML and save to file (most common usage)
+twentythree player embed --video-id 123 --responsive > embed.html
+
+# Generate embed code as structured JSON for programmatic use
+twentythree player embed --video-id 123 --responsive --autoplay --json
+```
+
+### player embed-versions
+
+**Auth scope:** read  **Side effects:** none  **Output:** table (Type, Key, Label)
+
+Lists available embed versions for a specific object. Requires both `--object-type` and `--object-id`.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-type` | yes | Object type: `photo`, `live`, `album`, or `site` |
+| `--object-id` | yes | Object ID |
+| `--source` | no | Embed source parameter (e.g. `embed`, `share`) |
+
+```bash
+# List embed versions for a video (use API legacy name 'photo')
+twentythree player embed-versions --object-type photo --object-id 123 --json
+
+# List embed versions for a webinar (use API legacy name 'live')
+twentythree player embed-versions --object-type live --object-id 456 --json
+```
+
+### player styles
+
+**Auth scope:** read  **Side effects:** none  **Output:** table (Style, Name, Icon)
+
+Lists available player visual styles. No required flags.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--fields` | no | Comma-separated list of fields to return |
+
+```bash
+# Discover all available player styles
+twentythree player styles --json
+
+# Request specific fields only
+twentythree player styles --fields style,name --json
+```
+
+## Common Patterns
+
+### Generate responsive embed code for a video
+
+```bash
+# Discover players to pick one, or use the workspace default
+twentythree player list --json
+
+# Generate a responsive, autoplay embed
+twentythree player embed --video-id <id> --responsive --autoplay --json
+
+# Save to file for use in HTML templates
+twentythree player embed --video-id <id> --responsive > embed.html
+```
+
+### Discover available styles before updating a player
+
+```bash
+# Step 1: List current players
+twentythree player list --json
+
+# Step 2: Check available visual styles
+twentythree player styles --json
+
+# Step 3: Update the player with a chosen style via --data
+twentythree player update <player-id> --name "Styled Player" --data '{"style":"minimal"}' --json
+```
+
+### Generate webinar embed for a live event
+
+```bash
+# Generate an iframe embed for a webinar (use API name 'live')
+twentythree player embed --webinar-id <webinar-id> --iframe --responsive --json
+
+# List embed versions for the webinar
+twentythree player embed-versions --object-type live --object-id <webinar-id> --json
+```