@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

npm install @suada/vanilla @suada/core

CDN

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

Setup

1. Initialize Suada in your application:

<!-- 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:

<!-- 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

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

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

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

await client.initialize();

OAuth Flow

// 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

// 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:

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:

.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:

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

# 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