Add Instagram strategy for posting content via Instagram Graph API

[Copilot]

This PR implements a comprehensive Instagram strategy for posting content to Instagram via the Instagram Graph API, addressing all requirements specified in the issue.

🎯 Key Features

Instagram Graph API Integration

• Two-step posting process: Creates media container then publishes it (Instagram requirement)
• OAuth 2.0 authentication: Supports access token-based authentication
• Business account support: Designed for Instagram Business accounts (personal accounts not supported)
• Image posting: Supports single image posts with captions

Technical Implementation

• Strategy pattern compliance: Follows existing strategy interface with id, name, post(), getUrlFromResponse(), MAX_MESSAGE_LENGTH, and calculateMessageLength()
• Custom upload function: Allows users to provide their own image upload implementation for CDN/hosting services
• Comprehensive validation: Validates all inputs and provides clear error messages
• AbortSignal support: Supports operation cancellation via AbortController
• Character limit: Enforces Instagram's 2200 character caption limit

Error Handling & Validation

• Validates access tokens and account IDs
• Rejects text-only posts (Instagram requires images)
• Limits to single image posts (carousel support not implemented)
• Provides detailed error messages for API failures
• Handles network timeouts and aborted requests

📋 API Documentation & Requirements

The implementation includes extensive documentation covering:

• Instagram Graph API: https://developers.facebook.com/docs/instagram-api/guides/content-publishing/
• OAuth Authentication: https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow
• App Registration: https://developers.facebook.com/docs/apps/
• Business account requirements and content type restrictions
• Rate limits: 200 requests per hour per user
• Image requirements: JPEG/PNG, 320px-8192px, 4:5 to 1.91:1 aspect ratio, <8MB

🔧 Usage Example

import { Client, InstagramStrategy } from '@humanwhocodes/crosspost';

const instagram = new InstagramStrategy({
  accessToken: 'your_instagram_access_token',
  instagramAccountId: 'your_business_account_id',
  uploadImageFn: async (image, accessToken, signal) => {
    // Upload image to your CDN/hosting service
    const url = await uploadToCDN(image.data);
    return url; // Must return publicly accessible URL
  }
});

const client = new Client({ strategies: [instagram] });

// Post with image
await client.post('Check out this amazing content! #instagram', {
  images: [{ data: imageBuffer, alt: 'Amazing content' }]
});

🧪 Testing

• 21 comprehensive test cases covering all functionality
• Constructor validation and error handling
• Post method with various input scenarios
• URL generation from API responses
• Character length calculation accuracy
• Integration with existing Client class
• All existing tests continue to pass

📝 Important Notes

• Image upload requirement: Users must provide their own uploadImageFn to upload images to a publicly accessible URL (CDN, S3, etc.) as Instagram requires public URLs
• Business accounts only: Instagram Graph API only supports business accounts, not personal accounts
• Single image limitation: Currently supports single image posts; carousel posts could be added in future iterations
• Rate limiting: Users should implement their own rate limiting to stay within Instagram's 200 requests/hour limit

Fixes #116.

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

• graph.facebook.com
  • Triggering command: node /home/REDACTED/work/crosspost/crosspost/node_modules/.bin/mocha tests/strategies/instagram.test.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.