npm package: @outstand-so/ui
Description: React UI components for Outstand.so Unified Social Media API
Author: Outstand.so
Latest version: 0.1.12

# @outstand-so/ui

React UI components for integrating with the [OutStand.so](https://outstand.so) Social Media API. Build beautiful social media management interfaces with pre-built, customizable components.

## Installation

```bash
npm install @outstand-so/ui
# or
yarn add @outstand-so/ui
# or
pnpm add @outstand-so/ui
```

## Quick Start

### 1. Wrap your app with the Provider (Optional)

```tsx
import { OutstandProvider } from '@outstand-so/ui'

function App() {
  return (
    <OutstandProvider 
      apiKey="your-api-key"
      tenantId="optional-tenant-id"
    >
      {/* Your app */}
    </OutstandProvider>
  )
}
```

### 2. Use Components

Each component can be used independently with its own `apiKey` prop, or use the context from `OutstandProvider`.

## Components

### Connect Account Buttons

```tsx
import { ConnectAccountButton, ConnectAccountButtonGroup } from '@outstand-so/ui'

// Single button
<ConnectAccountButton
  network="instagram"
  redirectUri="https://yourapp.com/callback"
  tenantId="user_123"
  apiKey="your-api-key"
  onSuccess={(authUrl) => console.log('Redirecting to:', authUrl)}
  onError={(error) => console.error(error)}
/>

// Multiple networks
<ConnectAccountButtonGroup
  networks={['instagram', 'facebook', 'x', 'linkedin']}
  redirectUri="https://yourapp.com/callback"
  tenantId="user_123"
  apiKey="your-api-key"
  layout="grid"
/>
```

### Media Uploader

```tsx
import { MediaUploader } from '@outstand-so/ui'

<MediaUploader
  apiKey="your-api-key"
  onUploadComplete={(files) => console.log('Uploaded:', files)}
  onUploadError={(error) => console.error(error)}
  maxFiles={4}
  acceptedTypes={['image/*', 'video/*']}
/>
```

### Create Post Form

```tsx
import { CreatePostForm } from '@outstand-so/ui'

<CreatePostForm
  apiKey="your-api-key"
  enableScheduling={true}
  onPostCreated={(post) => console.log('Posted:', post)}
  onError={(error) => console.error(error)}
/>
```

### Accounts List

```tsx
import { AccountsList } from '@outstand-so/ui'

<AccountsList
  apiKey="your-api-key"
  tenantId="user_123"
  pageSize={10}
  onAccountSelect={(account) => console.log('Selected:', account)}
  onAccountDisconnect={(id) => console.log('Disconnected:', id)}
/>
```

### OAuth Callback Handler

```tsx
import { OAuthCallback } from '@outstand-so/ui'

// Use on your callback page (e.g., /callback)
<OAuthCallback
  apiKey="your-api-key"
  onSuccess={(accounts) => {
    console.log('Connected accounts:', accounts)
    router.push('/dashboard')
  }}
  onError={(error) => console.error(error)}
/>
```

### Post Metrics

```tsx
import { PostMetrics, PostsWithMetrics } from '@outstand-so/ui'

// Single post metrics
<PostMetrics
  apiKey="your-api-key"
  postId="post_id"
  refreshInterval={60000} // Optional: auto-refresh every minute
/>

// List of posts with expandable metrics
<PostsWithMetrics
  apiKey="your-api-key"
  socialAccountId="account_id" // Optional: filter by account
  pageSize={10}
/>
```

## Styling

Components are built with Tailwind CSS. Import the styles or configure your own:

```tsx
// Option 1: Import built-in styles
import '@outstand-so/ui/styles.css'

// Option 2: Use your own Tailwind config (recommended)
// Components use standard Tailwind classes and CSS variables
```

### CSS Variables

Components use these CSS variables for theming:

```css
:root {
  --background: 0 0% 100%;
  --foreground: 0 0% 3.9%;
  --primary: 0 0% 9%;
  --primary-foreground: 0 0% 98%;
  --muted: 0 0% 96.1%;
  --muted-foreground: 0 0% 45.1%;
  --border: 0 0% 89.8%;
  --input: 0 0% 89.8%;
  --ring: 0 0% 63.9%;
  --destructive: 0 84.2% 60.2%;
}
```

## Hooks

All components are built on reusable hooks you can use directly:

```tsx
import { 
  useAccounts,
  usePosts,
  usePostMetrics,
  useMediaUpload,
  useOAuthFlow,
  useOutstandApi 
} from '@outstand-so/ui'

// Fetch accounts
const { accounts, isLoading, refetch } = useAccounts({
  apiKey: 'your-api-key',
  tenantId: 'user_123',
  limit: 50
})

// Create posts
const { createPost, posts } = usePosts({
  apiKey: 'your-api-key'
})

// Upload media
const { uploadFiles, isUploading } = useMediaUpload({
  apiKey: 'your-api-key'
})
```

## Supported Networks

- X (Twitter)
- Instagram
- Facebook
- LinkedIn
- YouTube
- TikTok
- Threads
- Bluesky
- Pinterest

## License

MIT