@bernierllc/social-media-instagram

Instagram Graph API integration service with OAuth 2.0 via Facebook, content posting (feed, stories, reels, carousels), and Instagram-specific features.

Features

• OAuth 2.0 authentication via Facebook
• Instagram Business and Creator account support
• Content posting:
  • Feed posts (images)
  • Stories (images and videos)
  • Reels
  • Carousels (planned)
• Media insights and analytics
• Two-step container-based publishing
• Account management

Installation

npm install @bernierllc/social-media-instagram

Usage

Basic Setup

import { InstagramService } from '@bernierllc/social-media-instagram';

const instagram = new InstagramService({
  appId: 'your-facebook-app-id',
  appSecret: 'your-facebook-app-secret',
  callbackUrl: 'https://your-app.com/callback',
  apiVersion: 'v18.0', // Optional, defaults to v18.0
});

Authentication

Instagram uses Facebook OAuth for authentication:

// After user completes Facebook OAuth flow
const facebookCredentials = {
  accessToken: 'user-access-token',
  expiresAt: Date.now() + 3600000,
};

const authResult = await instagram.authenticate(facebookCredentials);

if (authResult.success) {
  console.log('Authenticated as:', authResult.account?.username);
} else {
  console.error('Authentication failed:', authResult.error);
}

Posting Content

Post a Photo

const postResult = await instagram.postPhoto({
  caption: 'Hello Instagram!',
  imageUrl: 'https://example.com/image.jpg',
  mediaType: 'IMAGE',
  locationId: 'optional-location-id',
  userTags: [
    {
      userId: 'user-id',
      x: 0.5,
      y: 0.5,
    },
  ],
});

if (postResult.success) {
  console.log('Post URL:', postResult.url);
  console.log('Post ID:', postResult.postId);
}

Post a Reel

const reelResult = await instagram.postReel({
  videoUrl: 'https://example.com/video.mp4',
  caption: 'Check out this reel!',
  coverUrl: 'https://example.com/cover.jpg', // Optional
  audioName: 'trending-audio', // Optional
});

if (reelResult.success) {
  console.log('Reel container ID:', reelResult.containerId);
}

Post a Story

const storyResult = await instagram.postStory({
  mediaUrl: 'https://example.com/image.jpg',
  mediaType: 'IMAGE',
  linkUrl: 'https://example.com/link', // Optional, requires verified account
});

if (storyResult.success) {
  console.log('Story ID:', storyResult.storyId);
}

Get Media Insights

const insights = await instagram.getMediaInsights('media-id');

console.log('Impressions:', insights.impressions);
console.log('Reach:', insights.reach);
console.log('Engagement:', insights.engagement);
console.log('Likes:', insights.likes);
console.log('Comments:', insights.comments);
console.log('Saves:', insights.saves);

Account Management

// Check if authenticated
if (instagram.isAuthenticated()) {
  // Get account info
  const account = await instagram.getAccountInfo();
  console.log('Account ID:', account.id);
  console.log('Username:', account.username);
  console.log('Account Type:', account.accountType);
}

// Get current account
const currentAccount = instagram.getAccount();

API Reference

InstagramService

Constructor

new InstagramService(config: InstagramServiceConfig)

InstagramServiceConfig:

• appId (string, required): Facebook App ID
• appSecret (string, required): Facebook App Secret
• callbackUrl (string, required): OAuth callback URL
• apiVersion (string, optional): API version (default: 'v18.0')
• debug (boolean, optional): Enable debug logging

Methods

authenticate(credentials: FacebookCredentials): Promise

Authenticate using Facebook OAuth credentials.

postPhoto(content: InstagramContent): Promise

Post a photo to Instagram feed.

postReel(reel: InstagramReel): Promise

Post a reel to Instagram.

postStory(story: InstagramStory): Promise

Post a story to Instagram.

postCarousel(content: InstagramContent): Promise

Post a carousel (multiple images). Currently returns not implemented error.

getMediaInsights(mediaId: string): Promise

Get insights for a specific media post.

getAccountInfo(): Promise

Get information about the authenticated Instagram account.

selectAccount(accounts: InstagramAccount[]): Promise

Select a specific Instagram account from available accounts.

isAuthenticated(): boolean

Check if the service is authenticated.

getAccount(): InstagramAccount | null

Get the current selected account.

Requirements

• Node.js >= 18.0.0
• Facebook App with Instagram Graph API permissions
• Instagram Business or Creator account

Authentication Flow

1. Set up a Facebook App with Instagram Graph API permissions
2. Implement Facebook OAuth flow in your application
3. Exchange Facebook access token for Instagram access
4. Use the InstagramService to manage Instagram content

Limitations

• Carousel posting requires multiple images (not yet fully implemented)
• Post scheduling requires account approval (not yet fully implemented)
• Media upload to Facebook required for some operations (not yet fully implemented)
• Story links require verified accounts

Error Handling

All methods return results with success/error information:

const result = await instagram.postPhoto(content);

if (!result.success) {
  console.error('Error:', result.error);
  // Handle error
}

Testing

npm test                # Run tests in watch mode
npm run test:run       # Run tests once
npm run test:coverage  # Run tests with coverage

License

Copyright (c) 2025 Bernier LLC

This file is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.

Support

For issues and questions, please open an issue on the GitHub repository.