npm package: @mba-web-stories/sdk
Description: Internal SDK for MBA web stories
Author: Much Better Adventures
Latest version: 0.1.2

# @mba-web-stories/sdk

React SDK for embedding interactive web stories with video content.

## Installation

```bash
npm install @mba-web-stories/sdk
```

## Usage Options

### Option 1: Standard Usage (Recommended)

For most modern build systems (Next.js, Vite, Create React App with proper configuration):

```jsx
import { WebStories } from '@mba-web-stories/sdk'
// CSS will be handled by your build system
import '@mba-web-stories/sdk/styles'

function App() {
  return (
    <div style={{ width: '100%', height: '400px' }}>
      <WebStories
        galleryId="your-gallery-id"
        apiKey="your-api-key"
        config={{
          apiUrl: 'https://your-api.com/graphql',
          autoplay: false,
          showProgress: true,
          allowKeyboard: true
        }}
      />
    </div>
  )
}
```

### Option 2: Self-Contained (Maximum Compatibility)

For environments where CSS imports might not work:

```jsx
// This version has CSS inlined in JavaScript
import { WebStories } from '@mba-web-stories/sdk/inline'

function App() {
  return (
    <div style={{ width: '100%', height: '400px' }}>
      <WebStories
        galleryId="your-gallery-id"
        apiKey="your-api-key"
        config={{
          apiUrl: 'https://your-api.com/graphql'
        }}
      />
    </div>
  )
}
```

### Option 3: Manual CSS Import

For custom setups or when you need full control:

```jsx
import { WebStories } from '@mba-web-stories/sdk'
// Manually import CSS in your HTML or build process
// <link rel="stylesheet" href="node_modules/@mba-web-stories/sdk/dist/index.css">

function App() {
  return (
    <WebStories
      galleryId="your-gallery-id"
      apiKey="your-api-key"
    />
  )
}
```

## Build System Configuration

### Next.js

Add to your `next.config.js`:

```js
const nextConfig = {
  transpilePackages: ['@mba-web-stories/sdk']
}
```

### Vite

Usually works out of the box. If CSS imports fail, use the `/inline` version.

### Webpack

Ensure CSS loading is configured:

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader']
      }
    ]
  }
}
```

## API Reference

### WebStories Props

- `galleryId` (string, required): The ID of the gallery to display
- `apiKey` (string, required): Your API key for authentication  
- `config` (object, optional): Configuration options
- `className` (string, optional): Additional CSS class names

### Config Options

- `apiUrl` (string): GraphQL API endpoint
- `autoplay` (boolean): Auto-play videos when opened
- `showProgress` (boolean): Show progress bars
- `allowKeyboard` (boolean): Enable keyboard navigation
- `muted` (boolean): Start videos muted
- `customStyles` (object): Custom CSS styles
- `onStoryChange` (function): Callback when story changes
- `onStoryComplete` (function): Callback when story completes
- `onGalleryComplete` (function): Callback when gallery ends

## Defensive Styling

This SDK uses aggressive defensive CSS to ensure it works in any environment:

- ✅ **Scoped styles** - Won't interfere with your app's CSS
- ✅ **CSS reset** - Immune to external CSS interference  
- ✅ **High specificity** - Styles always apply correctly
- ✅ **Runtime injection** - CSS loads even if build system fails
- ✅ **Multiple build targets** - Works with any bundler

## Troubleshooting

### Styles Not Loading

1. Try the `/inline` import version
2. Check that your build system processes CSS imports
3. Manually import the CSS file
4. The SDK will inject fallback styles automatically

### Build Errors

- Ensure your bundler supports CSS imports
- Add the package to `transpilePackages` in Next.js
- Use the `/inline` version for problematic environments

### TypeScript Issues

Types are included automatically. If you have issues:

```typescript
import type { WebStoriesProps } from '@mba-web-stories/sdk'
```