nevo-david_postiz/INTEGRATION_SETTINGS_DISCOVERY.md

# Integration Settings Discovery

The CLI now has a powerful feature to discover what settings are available for each integration!

## New Command: `integrations:settings`

Get the settings schema, validation rules, and maximum character limits for any integration.

## Usage

```bash
postiz integrations:settings <integration-id>
```

## What It Returns

```json
{
  "output": {
    "maxLength": 280,
    "settings": {
      "properties": {
        "who_can_reply_post": {
          "enum": ["everyone", "following", "mentionedUsers", "subscribers", "verified"],
          "description": "Who can reply to this post"
        },
        "community": {
          "pattern": "^(https://x.com/i/communities/\\d+)?$",
          "description": "X community URL"
        }
      },
      "required": ["who_can_reply_post"]
    }
  }
}
```

## Workflow

### 1. List Your Integrations

```bash
postiz integrations:list
```

Output:
```json
[
  {
    "id": "reddit-abc123",
    "name": "My Reddit Account",
    "identifier": "reddit",
    "provider": "reddit"
  },
  {
    "id": "youtube-def456",
    "name": "My YouTube Channel",
    "identifier": "youtube",
    "provider": "youtube"
  },
  {
    "id": "twitter-ghi789",
    "name": "@myhandle",
    "identifier": "x",
    "provider": "x"
  }
]
```

### 2. Get Settings for Specific Integration

```bash
postiz integrations:settings reddit-abc123
```

Output:
```json
{
  "output": {
    "maxLength": 40000,
    "settings": {
      "properties": {
        "subreddit": {
          "type": "array",
          "items": {
            "properties": {
              "value": {
                "properties": {
                  "subreddit": {
                    "type": "string",
                    "minLength": 2,
                    "description": "Subreddit name"
                  },
                  "title": {
                    "type": "string",
                    "minLength": 2,
                    "description": "Post title"
                  },
                  "type": {
                    "type": "string",
                    "description": "Post type (text or link)"
                  },
                  "url": {
                    "type": "string",
                    "description": "URL for link posts"
                  },
                  "is_flair_required": {
                    "type": "boolean",
                    "description": "Whether flair is required"
                  },
                  "flair": {
                    "properties": {
                      "id": "string",
                      "name": "string"
                    }
                  }
                },
                "required": ["subreddit", "title", "type", "is_flair_required"]
              }
            }
          }
        }
      },
      "required": ["subreddit"]
    }
  }
}
```

### 3. Use the Settings in Your Post

Now you know what settings are available and required!

```bash
postiz posts:create \
  -c "My post content" \
  -p reddit \
  --settings '{
    "subreddit": [{
      "value": {
        "subreddit": "programming",
        "title": "Check this out!",
        "type": "text",
        "url": "",
        "is_flair_required": false
      }
    }]
  }' \
  -i "reddit-abc123"
```

## Examples by Platform

### Reddit

```bash
postiz integrations:settings reddit-abc123
```

Returns:
- Max length: 40,000 characters
- Required settings: subreddit, title, type
- Optional: flair

### YouTube

```bash
postiz integrations:settings youtube-def456
```

Returns:
- Max length: 5,000 characters (description)
- Required settings: title, type (public/private/unlisted)
- Optional: tags, thumbnail, selfDeclaredMadeForKids

### X (Twitter)

```bash
postiz integrations:settings twitter-ghi789
```

Returns:
- Max length: 280 characters (or 4,000 for verified)
- Required settings: who_can_reply_post
- Optional: community

### LinkedIn

```bash
postiz integrations:settings linkedin-jkl012
```

Returns:
- Max length: 3,000 characters
- Optional settings: post_as_images_carousel, carousel_name

### TikTok

```bash
postiz integrations:settings tiktok-mno345
```

Returns:
- Max length: 150 characters (caption)
- Required settings: privacy_level, duet, stitch, comment, autoAddMusic, brand_content_toggle, brand_organic_toggle, content_posting_method
- Optional: title, video_made_with_ai

### Instagram

```bash
postiz integrations:settings instagram-pqr678
```

Returns:
- Max length: 2,200 characters
- Required settings: post_type (post or story)
- Optional: is_trial_reel, graduation_strategy, collaborators

## No Additional Settings Required

Some platforms don't require specific settings:

```bash
postiz integrations:settings threads-stu901
```

Returns:
```json
{
  "output": {
    "maxLength": 500,
    "settings": "No additional settings required"
  }
}
```

Platforms with no additional settings:
- Threads
- Mastodon
- Bluesky
- Telegram
- Nostr
- VK

## Use Cases

### 1. Discovery

Find out what settings are available before posting:

```bash
# What settings does YouTube support?
postiz integrations:settings youtube-123

# What settings does Reddit support?
postiz integrations:settings reddit-456
```

### 2. Validation

Check maximum character limits:

```bash
postiz integrations:settings twitter-789 | jq '.output.maxLength'
# Output: 280
```

### 3. AI Agent Integration

AI agents can call this endpoint to:
- Discover available settings dynamically
- Validate settings before posting
- Adapt to platform-specific requirements

```bash
# Get settings schema
INTEGRATION_ID="your-integration-id"
SETTINGS=$(postiz integrations:settings "$INTEGRATION_ID")

# Extract max length
MAX_LENGTH=$(echo "$SETTINGS" | jq '.output.maxLength')

# Check and truncate content if needed
CONTENT="Your post content"
if [ ${#CONTENT} -gt "$MAX_LENGTH" ]; then
  CONTENT="${CONTENT:0:$MAX_LENGTH}"
fi

# List required settings
echo "$SETTINGS" | jq '.output.settings.required // []'
```

### 4. Form Generation

Use the schema to generate UI forms:

```bash
# Inspect the settings schema for form generation
postiz integrations:settings reddit-123 | jq '.output.settings'

# Extract specific field properties
postiz integrations:settings reddit-123 \
  | jq '.output.settings.properties.subreddit.items.properties.value.properties'
# → subreddit (text, minLength: 2)
# → title (text, minLength: 2)
# → type (select: text/link)
# → etc.
```

## Combined Workflow

Complete workflow for posting with correct settings:

```bash
#!/bin/bash
export POSTIZ_API_KEY=your_key

# 1. List integrations
echo "📋 Available integrations:"
postiz integrations:list

# 2. Get settings for Reddit
echo ""
echo "⚙️  Reddit settings:"
SETTINGS=$(postiz integrations:settings reddit-123)
echo $SETTINGS | jq '.output.maxLength'
echo $SETTINGS | jq '.output.settings'

# 3. Create post with correct settings
echo ""
echo "📝 Creating post..."
postiz posts:create \
  -c "My post content" \
  -p reddit \
  --settings '{
    "subreddit": [{
      "value": {
        "subreddit": "programming",
        "title": "Interesting post",
        "type": "text",
        "url": "",
        "is_flair_required": false
      }
    }]
  }' \
  -i "reddit-123"
```

## API Endpoint

The command calls:
```
GET /public/v1/integration-settings/:id
```

Returns:
```typescript
{
  output: {
    maxLength: number;
    settings: ValidationSchema | "No additional settings required";
  }
}
```

## Error Handling

### Integration Not Found

```bash
postiz integrations:settings invalid-id
# ❌ Failed to get integration settings: Integration not found
```

### API Key Not Set

```bash
postiz integrations:settings reddit-123
# ❌ Error: POSTIZ_API_KEY environment variable is required
```

## Tips

1. **Always check settings first** before creating posts with custom settings
2. **Use the schema** to validate your settings object
3. **Check maxLength** to avoid exceeding character limits
4. **For AI agents**: Cache the settings to avoid repeated API calls
5. **Required fields** must be included in your settings object

## Comparison: Before vs After

### Before ❌

```bash
# Had to guess what settings are available
# Had to read documentation or source code
# Didn't know character limits
```

### After ✅

```bash
# Discover settings programmatically
postiz integrations:settings reddit-123

# See exactly what's required and optional
# Know the exact character limits
# Get validation schemas
```

## Summary

✅ **Discover settings for any integration**
✅ **Get character limits**
✅ **See validation schemas**
✅ **Know required vs optional fields**
✅ **Perfect for AI agents**
✅ **No more guesswork!**

**Now you can discover what settings each platform supports!** 🎉