npm package: @olastudio/social-media-sdk
Description: Modular SDK for managing authentication and APIs of multiple social media platforms
Author: Oktopus Dev
Latest version: 0.3.3

# @olastudio/social-media-sdk

Modular SDK for managing authentication and APIs of multiple social media platforms.

## Installation

```bash
npm install @olastudio/social-media-sdk
```

## Supported Platforms

- **Facebook** - Pages management, posts publishing, insights
- **Instagram** - Account insights, media management, content publishing
- **TikTok** - User info, video list, account insights, content publishing

## Quick Start

### Initialize Providers

```typescript
import { FacebookProvider, InstagramProvider, TikTokProvider } from '@olastudio/social-media-sdk';

// Facebook
const facebookProvider = new FacebookProvider({
  appId: 'YOUR_FACEBOOK_APP_ID',
});

// Instagram
const instagramProvider = new InstagramProvider({
  appId: 'YOUR_FACEBOOK_APP_ID', // Instagram uses Facebook App ID
});

// TikTok
const tiktokProvider = new TikTokProvider({
  clientKey: 'YOUR_TIKTOK_CLIENT_KEY',
});
```

### Set Access Token

```typescript
// After obtaining user's access token via OAuth
facebookProvider.setAccessToken(userAccessToken);
instagramProvider.setAccessToken(userAccessToken);
tiktokProvider.setAccessToken(userAccessToken);
```

## Facebook API

### Get User Pages

```typescript
const pages = await facebookProvider.api.getPages();
console.log('User pages:', pages);
```

### Get Page Insights

```typescript
const insights = await facebookProvider.api.getPageInsights(pageId, {
  metric: ['page_impressions', 'page_engaged_users'],
  period: 'day',
  since: startTimestamp,
  until: endTimestamp,
});
```

### Publish Post

```typescript
// Text only
const post = await facebookProvider.api.publishPost({
  pageId: 'PAGE_ID',
  pageAccessToken: 'PAGE_ACCESS_TOKEN',
  message: 'Hello from the SDK!',
});

// With photo
const photoPost = await facebookProvider.api.publishPost({
  pageId: 'PAGE_ID',
  pageAccessToken: 'PAGE_ACCESS_TOKEN',
  message: 'Check out this photo!',
  imageUrl: 'https://example.com/photo.jpg',
});
```

### Get Fan Count

```typescript
const fansData = await facebookProvider.api.getPageFansCount(pageId);
console.log('Fans:', fansData.fan_count);
```

## Instagram API

### Get Account Info

```typescript
const account = await instagramProvider.api.getAccount(accountId);
console.log('Account:', account);
```

### Get Account Insights

```typescript
const insights = await instagramProvider.api.getAccountInsights(accountId, {
  metric: ['reach', 'impressions', 'profile_views'],
  period: 'day',
  since: startTimestamp,
  until: endTimestamp,
});
```

### Get Media

```typescript
const media = await instagramProvider.api.getMedia(accountId, 25);
console.log('Recent media:', media);
```

### Publish Photo

```typescript
const post = await instagramProvider.api.publishPhoto({
  instagramAccountId: 'IG_ACCOUNT_ID',
  imageUrl: 'https://example.com/photo.jpg',
  caption: 'Hello Instagram!',
});
```

### Publish Reel

```typescript
const reel = await instagramProvider.api.publishReel({
  instagramAccountId: 'IG_ACCOUNT_ID',
  videoUrl: 'https://example.com/video.mp4',
  caption: 'My new reel!',
  coverUrl: 'https://example.com/cover.jpg',
});
```

## TikTok API

### Get User Info

```typescript
const userInfo = await tiktokProvider.api.getUserInfo();
console.log('User:', userInfo);
```

### Get Account Insights

```typescript
const insights = await tiktokProvider.api.getAccountInsights();
console.log('Insights:', insights);
// Returns: followerCount, followingCount, likesCount, videoCount, totalViews, averageEngagementRate
```

### Get Video List

```typescript
const videos = await tiktokProvider.api.getVideoList({ maxCount: 20 });
console.log('Videos:', videos);
```

### Get Video Insights

```typescript
const videoInsights = await tiktokProvider.api.getVideoInsights('VIDEO_ID');
console.log('Video metrics:', videoInsights);
```

## OAuth Authentication (React Native/Expo)

For mobile apps using Expo, import the ExpoAdapter separately:

```typescript
import { ExpoAdapter } from '@olastudio/social-media-sdk/adapters/expo';
import { FacebookProvider } from '@olastudio/social-media-sdk';

const oauthAdapter = new ExpoAdapter();
const facebookProvider = new FacebookProvider({ appId: 'YOUR_APP_ID' });

// Get OAuth config
const oauthConfig = facebookProvider.auth.getOAuthConfig(
  ['public_profile', 'email', 'pages_manage_posts'],
  'YOUR_REDIRECT_URI'
);

// Start OAuth flow
const result = await oauthAdapter.startAuthFlow(oauthConfig);

if (result.type === 'success' && result.accessToken) {
  facebookProvider.setAccessToken(result.accessToken);
  // Now you can use the API
}
```

## Advanced Usage

### Custom HTTP Client Configuration

```typescript
const provider = new FacebookProvider({
  appId: 'YOUR_APP_ID',
  apiVersion: 'v18.0', // Optional, defaults to v24.0
});
```

### Error Handling

```typescript
import { APIError, AuthError } from '@olastudio/social-media-sdk';

try {
  const insights = await instagramProvider.api.getAccountInsights(accountId, {
    metric: ['reach'],
    period: 'day',
  });
} catch (error) {
  if (error instanceof APIError) {
    console.error('API Error:', error.message, error.statusCode);
  } else if (error instanceof AuthError) {
    console.error('Auth Error:', error.message);
  }
}
```

## TypeScript Support

The SDK is written in TypeScript and includes full type definitions.

```typescript
import type {
  FacebookPage,
  InstagramAccount,
  InstagramMedia,
  TikTokUserInfo,
  PageInsightsParams,
  AccountInsightsParams,
} from '@olastudio/social-media-sdk';
```

## License

MIT