Creagency Agent Skill Reference

// Error handling decision tree for agents
class CreagencyErrorHandler {
  handle(error: ApiError): AgentAction {
    const { status, code, message } = error;

    // 401: Authentication failure
    if (status === 401) {
      return {
        type: 'STOP',
        userMessage: 
          'API key is invalid, expired, or revoked. ' +
          'Please check your CREAGENCY_API_KEY environment variable ' +
          'or generate a new key in the dashboard.'
      };
    }

    // 403: Scope/permission issue
    if (status === 403) {
      if (code === 'UPGRADE_REQUIRED') {
        return {
          type: 'ASK_USER',
          userMessage: 
            'This operation requires a higher plan. ' +
            'Current plan: Starter. Required: Growth+. ' +
            'Would you like me to open the billing page?'
        };
      }
      
      return {
        type: 'STOP',
        userMessage: 
          'API key lacks required scope for this operation. ' +
          'This key is missing a required scope for the attempted workflow. ' +
          'Continue with a reduced workflow or create a key with the exact scope needed.'
      };
    }

    // 429: Rate limited
    if (status === 429) {
      const resetSeconds = error.headers['ratelimit-reset'];
      
      return {
        type: 'WAIT',
        waitSeconds: parseInt(resetSeconds) + 1,
        userMessage: 
          `Rate limit hit. Waiting ${resetSeconds} seconds before retry...`
      };
    }

    // 400: Validation error
    if (status === 400) {
      // Extract field-specific errors
      const fieldErrors = error.details?.fields;
      
      if (fieldErrors) {
        const fields = Object.keys(fieldErrors).join(', ');
        return {
          type: 'ASK_USER',
          userMessage: 
            `Validation failed for fields: ${fields}. ` +
            'Please correct the input and try again.'
        };
      }
      
      return {
        type: 'ASK_USER',
        userMessage: 
          `Request validation failed: ${message}. ` +
          'Please check the data format and try again.'
      };
    }

    // 500+: Server errors
    if (status >= 500) {
      return {
        type: 'RETRY',
        maxRetries: 3,
        backoffMs: 1000,
        userMessage: 
          'Server error occurred. Will retry with exponential backoff...'
      };
    }

    // Default: Unknown error
    return {
      type: 'STOP',
      userMessage: 
        `Unexpected error (${status}): ${message}. ` +
        'Please try again or contact support.'
    };
  }
}

// Rate limit handling pattern
class RateLimitManager {
  private remaining: number = 60;
  private resetTime: Date = new Date();
  private minRemaining: number = 5;

  async executeWithRateLimit<T>(
    operation: () => Promise<{ headers: Headers; data: T }>
  ): Promise<T> {
    // Pre-check: If running low, wait proactively
    if (this.remaining <= this.minRemaining) {
      const waitMs = this.resetTime.getTime() - Date.now();
      if (waitMs > 0) {
        console.log('Rate limit buffer low. Pausing for ' + waitMs + 'ms...');
        await sleep(waitMs);
      }
    }

    try {
      const response = await operation();
      
      // Update rate limit tracking from headers
      this.remaining = parseInt(response.headers['ratelimit-remaining'] || '0');
      const resetSeconds = parseInt(response.headers['ratelimit-reset'] || '60');
      this.resetTime = new Date(Date.now() + resetSeconds * 1000);
      
      return response.data;
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = parseInt(error.headers['retry-after'] || '60');
        console.log('Rate limited. Waiting ' + retryAfter + 's...');
        await sleep(retryAfter * 1000);
        
        // Retry once
        const retry = await operation();
        return retry.data;
      }
      throw error;
    }
  }
}

// Tool definition pattern for AI agents
// Use this when integrating Creagency into your agent's tool system

const creagencyTools = [
  {
    name: 'creagency_list_posts',
    description: 'List posts for the organization with optional filtering',
    parameters: {
      type: 'object',
      properties: {
        platform: {
          type: 'string',
          enum: ['x', 'linkedin', 'instagram', 'youtube', 'tiktok', 'facebook', 'threads'],
          description: 'Filter by social platform'
        },
        q: {
          type: 'string',
          description: 'Search term for post content'
        },
        limit: {
          type: 'integer',
          minimum: 1,
          maximum: 100,
          default: 20,
          description: 'Number of posts to return'
        },
        favoriteOnly: {
          type: 'boolean',
          description: 'Return only favorited posts'
        }
      }
    },
    requiredScopes: ['posts:read']
  },
  {
    name: 'creagency_create_post',
    description: 'Create a new post draft or scheduled post',
    parameters: {
      type: 'object',
      properties: {
        content: {
          type: 'string',
          maxLength: 63206,
          description: 'Post content/caption'
        },
        platforms: {
          type: 'array',
          items: { type: 'string' },
          minItems: 1,
          description: 'Target platforms (e.g., ["x", "linkedin"])'
        },
        scheduledAt: {
          type: 'string',
          format: 'date-time',
          description: 'ISO 8601 datetime for scheduling. Omit for draft.'
        },
        assetIds: {
          type: 'array',
          items: { type: 'string' },
          description: 'Media asset IDs to attach'
        }
      },
      required: ['content', 'platforms']
    },
    requiredScopes: ['posts:write']
  },
  {
    name: 'creagency_upload_media',
    description: 'Upload media file and create asset',
    parameters: {
      type: 'object',
      properties: {
        filePath: {
          type: 'string',
          description: 'Local path to media file'
        },
        filename: {
          type: 'string',
          description: 'Desired filename for the asset'
        }
      },
      required: ['filePath']
    },
    requiredScopes: ['assets:write']
  },
  {
    name: 'creagency_publish_post',
    description: 'Queue an existing post for immediate publishing',
    parameters: {
      type: 'object',
      properties: {
        postId: {
          type: 'string',
          description: 'ID of the post to publish'
        }
      },
      required: ['postId']
    },
    requiredScopes: ['posts:write']
  },
  {
    name: 'creagency_list_connected_accounts',
    description: 'List connected social media accounts',
    parameters: {
      type: 'object',
      properties: {}
    },
    requiredScopes: ['integrations:read']
  }
];

// Advanced Workflow 1: Create Post with AI-Generated Caption
async function createPostWithAiCaption(params: {
  topic: string;
  platform: 'x' | 'linkedin' | 'instagram';
  tone?: 'professional' | 'casual' | 'witty';
  scheduledAt?: string;
}) {
  console.log('[Workflow] Generating AI caption...');
  
  // Step 1: Generate caption
  const captionJob = await apiPost('/api/posts/ai/caption-jobs', {
    content: params.topic,
    platform: params.platform,
    tone: params.tone || 'professional'
  });
  
  // Step 2: Poll for completion (max 30s)
  let caption: string | null = null;
  const startTime = Date.now();
  
  while (Date.now() - startTime < 30000) {
    const status = await apiGet('/api/posts/ai/caption-jobs/' + captionJob.id);
    
    if (status.status === 'completed') {
      caption = status.result;
      break;
    }
    if (status.status === 'failed') {
      throw new Error('Caption generation failed: ' + status.error);
    }
    
    await sleep(2000); // Poll every 2s
  }
  
  if (!caption) {
    throw new Error('Caption generation timed out');
  }
  
  console.log('[Workflow] Caption generated, creating post...');
  
  // Step 3: Create post with generated caption
  const post = await apiPost('/api/posts', {
    content: caption,
    platforms: [params.platform],
    scheduledAt: params.scheduledAt
  });
  
  return {
    success: true,
    postId: post.id,
    caption: caption,
    url: 'https://app.creagency.ai/dashboard/posts/' + post.id
  };
}

// Advanced Workflow 2: Cross-Post to Multiple Platforms
async function crossPostToMultiplePlatforms(params: {
  content: string;
  platforms: string[];
  scheduledAt?: string;
  assetIds?: string[];
}) {
  console.log('[Workflow] Cross-posting to ' + params.platforms.length + ' platforms...');
  
  // Step 1: Verify all platforms connected when integrations:read is available
  try {
    const accounts = await apiGet('/api/integrations/social/accounts');
    const connectedPlatforms = new Set(accounts.map((a: any) => a.platform));

    const missing = params.platforms.filter(p => !connectedPlatforms.has(p));
    if (missing.length > 0) {
      throw new Error(
        'Not connected to: ' + missing.join(', ') + '. ' +
        'Connect accounts in dashboard first.'
      );
    }
  } catch (error: any) {
    if (error?.status !== 403) {
      throw error;
    }
  }
  
  // Step 2: Create single post targeting all platforms
  const post = await apiPost('/api/posts', {
    content: params.content,
    platforms: params.platforms,
    scheduledAt: params.scheduledAt,
    assetIds: params.assetIds
  });
  
  console.log('Created cross-post: ' + post.id);
  
  return {
    success: true,
    postId: post.id,
    platforms: params.platforms,
    url: 'https://app.creagency.ai/dashboard/posts/' + post.id
  };
}

// Advanced Workflow 3: Reschedule Failed Posts
async function rescheduleFailedPosts(options?: {
  newScheduledAt?: string;
  platform?: string;
}) {
  console.log('[Workflow] Finding failed posts...');
  
  // Get all posts
  const posts = await apiGet('/api/posts?limit=100');
  
  // Filter for failed posts
  const failedPosts = posts.filter((p: any) => 
    p.status === 'failed' &&
    (!options?.platform || p.platforms.includes(options.platform))
  );

  console.log('Found ' + failedPosts.length + ' failed posts');

  let rescheduled = 0;
  let failed = 0;

  for (const post of failedPosts) {
    try {
      const newTime = options?.newScheduledAt || 
        new Date(Date.now() + 3600000).toISOString();

      await apiPatch('/api/posts/' + post.id, {
        scheduledAt: newTime
      });
      
      console.log('Rescheduled post ' + post.id);
      rescheduled++;
    } catch (err) {
      console.log('Failed to reschedule ' + post.id + ': ' + err);
      failed++;
    }
  }
  
  return { rescheduled, failed };
}

// Advanced Workflow 4: Bulk Create with Rate Limiting
async function bulkCreatePosts(postsData: Array<{
  content: string;
  platform: string;
  scheduledAt?: string;
}>) {
  console.log('[Workflow] Bulk creating ' + postsData.length + ' posts...');

  let created = 0;
  let failed = 0;
  const results: any[] = [];

  for (let i = 0; i < postsData.length; i++) {
    const data = postsData[i];
    console.log('  [' + (i + 1) + '/' + postsData.length + '] Creating post...');

    try {
      const post = await apiPost('/api/posts', {
        content: data.content,
        platforms: [data.platform],
        scheduledAt: data.scheduledAt
      });
      results.push(post);
      created++;

      // Rate limiting safety: posts limited to 10/minute
      if (i > 0 && i % 5 === 0 && i < postsData.length - 1) {
        console.log('  [Rate limit safety: pausing 10s...]');
        await sleep(10000);
      }
    } catch (err) {
      console.log('  Failed: ' + err);
      failed++;
    }
  }
  
  return { created, failed, results };
}

// Helper functions
const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
const apiGet = (path: string) => { /* ... */ return {} as any; };
const apiPost = (path: string, data: any) => { /* ... */ return {} as any; };
const apiPatch = (path: string, data: any) => { /* ... */ return {} as any; };