npm package: @suada/core
Description: Core functionality for Suada's integration management components
Author: Suada AI
Latest version: 1.0.0-rc.38

# @suada/core

Core functionality for Suada's integration management components. This package provides the foundation for all Suada front-end SDKs.

## Installation

```bash
npm install @suada/core
```

## Usage

```typescript
import { SuadaClient } from '@suada/core';

const client = new SuadaClient({
  apiKey: 'your-api-key',
  externalUserIdentifier: 'user-123',
  gridColumns: 3, // Optional: Set number of columns in the grid (default: 3)
});

// Initialize the client
await client.initialize();

// Use the client to manage integrations
const integrations = await client.getIntegrations();
```

## Features

### Core Client
The `SuadaClient` class provides the main interface for interacting with Suada's API:

- **Authentication Management**: Handles API authentication and token management
- **Integration Management**: Methods for managing third-party integrations
- **Organization Context**: Support for multi-organization environments
- **Type-safe API**: Full TypeScript support with comprehensive type definitions
- **Customizable Grid Layout**: Configure the number of columns in the integration grid

### Integration Types
Built-in support for various integration types:

- Notion
- Slack
- Google Analytics
- Linear
- Jira
- HubSpot
- Zoho
- More integrations coming soon...

### OAuth Flow Support
Simplified OAuth flow management:

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

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

### Error Handling
Comprehensive error handling with detailed error types:

```typescript
try {
  await client.someOperation();
} catch (error) {
  if (error instanceof SuadaAuthError) {
    // Handle authentication errors
  } else if (error instanceof SuadaApiError) {
    // Handle API errors
  }
}
```

## Configuration Options

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| apiKey | `string` | Yes | - | Your Suada API key |
| externalUserIdentifier | `string` | Yes | - | Identifier for the user |
| baseUrl | `string` | No | Suada API URL | Custom API URL if needed |
| theme | `object` | No | Default theme | Custom theme options |
| size | `'small' \| 'medium' \| 'large'` | No | `'medium'` | Size of the component |
| gridColumns | `number` | No | `3` | Number of columns in the integration grid |
| enabledIntegrations | `string[]` | No | All integrations | List of integration types to enable |
| onIntegrationConnected | `function` | No | - | Callback when integration is connected |
| onIntegrationDisconnected | `function` | No | - | Callback when integration is disconnected |
| onError | `function` | No | - | Callback when an error occurs |

## Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Build the package
npm run build

# Run linting
npm run lint

# Run type checking
npm run typecheck
```

## API Reference

### SuadaClient
The main client class for interacting with Suada's API.

#### Constructor Options
```typescript
interface SuadaClientOptions {
  apiKey: string;
  externalUserIdentifier: string;
  gridColumns?: number;
  baseUrl?: string;
}
```

#### Methods
- `initialize()`: Initialize the client
- `getIntegrations()`: Get all available integrations
- `createIntegration(type: string, config: IntegrationConfig)`: Create a new integration
- `deleteIntegration(id: string)`: Delete an integration
- `initializeOAuth(provider: string, options: OAuthOptions)`: Initialize OAuth flow
- `handleOAuthCallback(provider: string, params: OAuthCallbackParams)`: Handle OAuth callback

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