npm package: @suada/vanilla
Description: Vanilla JavaScript components for Suada integrations
Latest version: 1.0.0-rc.18

# @suada/vanilla

Framework-agnostic JavaScript components for Suada integrations. This package provides vanilla JavaScript implementations that integrate with @suada/core, perfect for projects not using a specific framework.

## Installation

### NPM
```bash
npm install @suada/vanilla @suada/core
```

### CDN
```html
<script src="https://cdn.jsdelivr.net/npm/@suada/vanilla/dist/suada.min.js"></script>
```

## Setup

1. Initialize Suada in your application:

```html
<!-- Include the package -->
<script src="node_modules/@suada/vanilla/dist/suada.min.js"></script>

<script>
  // Initialize Suada client
  const suada = new Suada.Client({
    apiKey: 'your-api-key',
    organizationId: 'your-organization-id' // Optional
  });

  // Initialize the client
  await suada.initialize();
</script>
```

2. Use Suada components:

```html
<!-- Integration Button -->
<div id="notion-button"></div>

<!-- Integration List -->
<div id="integrations-list"></div>

<script>
  // Create an integration button
  const button = new Suada.IntegrationButton({
    container: '#notion-button',
    provider: 'notion',
    redirectUri: 'https://your-app.com/callback',
    text: 'Connect Notion',
    onSuccess: (result) => {
      console.log('Integration successful:', result);
    },
    onError: (error) => {
      console.error('Integration failed:', error);
    }
  });

  // Create an integration list
  const list = new Suada.IntegrationList({
    container: '#integrations-list',
    filter: { provider: 'notion' },
    layout: 'grid',
    onSelect: (integration) => {
      console.log('Selected integration:', integration);
    }
  });
</script>
```

## Components

### IntegrationButton
A button component that handles the OAuth flow for integrations.

#### Options
```typescript
interface IntegrationButtonOptions {
  container: string | HTMLElement;
  provider: string;
  redirectUri: string;
  text?: string;
  className?: string;
  style?: Partial<CSSStyleDeclaration>;
  loading?: boolean;
  onSuccess?: (result: IntegrationResult) => void;
  onError?: (error: Error) => void;
  onClick?: () => void;
}
```

#### Methods
- `initialize()`: Initialize the button
- `destroy()`: Clean up the button
- `setLoading(loading: boolean)`: Update loading state
- `setDisabled(disabled: boolean)`: Update disabled state

### IntegrationList
A component that displays a list of integrated services.

#### Options
```typescript
interface IntegrationListOptions {
  container: string | HTMLElement;
  filter?: IntegrationFilter;
  layout?: 'grid' | 'list';
  className?: string;
  style?: Partial<CSSStyleDeclaration>;
  itemClassName?: string;
  itemStyle?: Partial<CSSStyleDeclaration>;
  onSelect?: (integration: Integration) => void;
  onDelete?: (integration: Integration) => void;
}
```

#### Methods
- `initialize()`: Initialize the list
- `destroy()`: Clean up the list
- `refresh()`: Refresh the list data
- `setFilter(filter: IntegrationFilter)`: Update the filter
- `setLayout(layout: 'grid' | 'list')`: Update the layout

## Client API

### Initialization
```javascript
const client = new Suada.Client({
  apiKey: 'your-api-key',
  organizationId: 'your-organization-id'
});

await client.initialize();
```

### OAuth Flow
```javascript
// Initialize OAuth flow
const authUrl = await client.initializeOAuth('notion', {
  redirectUri: 'https://your-app.com/callback'
});
window.location.href = authUrl;

// Handle OAuth callback
const result = await client.handleOAuthCallback('notion', {
  code: 'auth-code',
  state: 'state-token'
});
```

### Integration Management
```javascript
// Get all integrations
const integrations = await client.getIntegrations();

// Get specific integration
const integration = await client.getIntegration('notion');

// Delete integration
await client.deleteIntegration('integration-id');
```

## Error Handling

The package includes typed error classes for better error handling:

```javascript
try {
  await client.someOperation();
} catch (error) {
  if (error instanceof Suada.AuthError) {
    // Handle authentication errors
  } else if (error instanceof Suada.ApiError) {
    // Handle API errors
  }
}
```

## Styling

### CSS Classes
The package provides CSS classes for styling:

```css
.suada-button { /* Button styles */ }
.suada-button--loading { /* Loading state */ }
.suada-button--disabled { /* Disabled state */ }

.suada-list { /* List container */ }
.suada-list--grid { /* Grid layout */ }
.suada-list--list { /* List layout */ }
.suada-list-item { /* List item */ }
```

### Custom Styling
You can also provide custom styles:

```javascript
const button = new Suada.IntegrationButton({
  // ...
  className: 'custom-button',
  style: {
    backgroundColor: '#f0f0f0',
    borderRadius: '8px'
  }
});
```

## Browser Support

- Chrome 60+
- Firefox 60+
- Safari 12+
- Edge 79+
- iOS Safari 12+
- Android Chrome 60+

## Development

```bash
# Install dependencies
npm install

# Build the library
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Run type checking
npm run typecheck
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT