@walker-di/fortalece-ai-sdk

Web Components library for Fortalece AI integration. Provides <support-chat> and <feedback-panel> custom elements that can be used in any web application.

Features

• Support Chat Widget: Interactive chat interface for customer support
• Feedback Panel: Form for collecting user feedback, bug reports, and feature requests
• Web Components: Works with any framework (React, Vue, Angular, vanilla JS)
• CDN Ready: Load directly from CDN with no build step required
• Customizable: Theming, positioning, and styling options
• TypeScript Support: Full type definitions included
• Lightweight: Minimal bundle size with no external dependencies

Installation

CDN Usage (Recommended for quick integration)

Add the script tag to your HTML:

<script src="https://cdn.jsdelivr.net/npm/@walker-di/fortalece-ai-sdk/dist/fortalece-ai-sdk.iife.js"></script>

Then use the components:

<support-chat project-id="your-project-id"></support-chat>
<feedback-panel project-id="your-project-id"></feedback-panel>

npm Installation

npm install @walker-di/fortalece-ai-sdk

// Import to auto-register custom elements
import '@walker-di/fortalece-ai-sdk';

Or use specific exports:

import { sendMessage, submitFeedback, createApiConfig } from '@walker-di/fortalece-ai-sdk';

Components

<support-chat>

Interactive chat widget for customer support.

<support-chat
  project-id="your-project-id"
  api-url="https://api.fortalece.ai"
  position="bottom-right"
  theme="light"
  primary-color="#6366f1"
  welcome-message="Hi! How can I help you?"
  placeholder="Type a message..."
></support-chat>

Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | project-id | string | required | Your Fortalece AI project ID | | api-url | string | https://api.fortalece.ai | API endpoint URL | | position | bottom-right | bottom-left | bottom-right | Widget position | | theme | light | dark | auto | light | Color theme | | primary-color | string | #6366f1 | Primary accent color (hex) | | welcome-message | string | Hi there! How can I help you today? | Initial welcome message | | placeholder | string | Type a message... | Input placeholder text |

<feedback-panel>

Feedback collection widget with form.

<feedback-panel
  project-id="your-project-id"
  api-url="https://api.fortalece.ai"
  position="bottom-left"
  theme="light"
  primary-color="#6366f1"
  show-priority="true"
  allow-attachments="false"
></feedback-panel>

Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | project-id | string | required | Your Fortalece AI project ID | | api-url | string | https://api.fortalece.ai | API endpoint URL | | position | bottom-right | bottom-left | bottom-right | Widget position | | theme | light | dark | auto | light | Color theme | | primary-color | string | #6366f1 | Primary accent color (hex) | | show-priority | boolean | true | Show priority selector | | allow-attachments | boolean | false | Allow file attachments |

Programmatic API

For advanced usage, you can use the API client directly:

import { sendMessage, submitFeedback, createApiConfig } from '@walker-di/fortalece-ai-sdk';

// Create API configuration
const config = createApiConfig('your-project-id', {
  apiUrl: 'https://api.fortalece.ai',
  apiKey: 'optional-api-key'
});

// Send a chat message
const chatResponse = await sendMessage(config, 'Hello, I need help!');
if (chatResponse.success) {
  console.log('Assistant:', chatResponse.message.content);
}

// Submit feedback
const feedbackResponse = await submitFeedback(config, {
  type: 'feature',
  title: 'New Feature Request',
  description: 'I would like to see...',
  priority: 'medium',
  email: '[email protected]'
});
if (feedbackResponse.success) {
  console.log('Feedback submitted:', feedbackResponse.feedbackId);
}

Types

import type {
  ApiConfig,
  ChatMessage,
  MessageRole,
  SendMessageRequest,
  SendMessageResponse,
  FeedbackRequest,
  FeedbackResponse,
  FeedbackType,
  FeedbackPriority,
  SupportChatConfig,
  FeedbackPanelConfig
} from '@walker-di/fortalece-ai-sdk';

Customization

CSS Custom Properties

Both components support CSS custom properties for styling:

support-chat,
feedback-panel {
  --fortalece-primary: #6366f1;
  --fortalece-bg: #ffffff;
  --fortalece-bg-secondary: #f9fafb;
  --fortalece-text: #1f2937;
  --fortalece-text-muted: #6b7280;
  --fortalece-border: #e5e7eb;
}

Shadow DOM

Components use Shadow DOM for style encapsulation. This ensures your page styles don't affect the widget appearance and vice versa.

Browser Support

• Chrome 67+
• Firefox 63+
• Safari 10.1+
• Edge 79+

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build library
npm run build:lib

# Run tests
npm test

Demo

Visit /demo in the development server to test the components with live configuration.

CI/CD

This package uses GitHub Actions for CI/CD:

• CI: Runs on every push/PR to main that modifies packages/fortalece-ai-sdk/

  • Type checking
  • Library build
  • E2E tests

• Publish: Runs on version tags (fortalece-ai-sdk@*) or manual trigger

  • Publishes to npm
  • Creates GitHub release with artifacts

Releasing a New Version

1. Update the version in package.json
2. Update CHANGELOG.md
3. Commit changes: git commit -am "chore: release @walker-di/[email protected]"
4. Create a tag: git tag [email protected]
5. Push with tags: git push --follow-tags

Or use the convenience scripts:

# Patch release (0.1.0 -> 0.1.1)
npm run release:patch

# Minor release (0.1.0 -> 0.2.0)
npm run release:minor

# Major release (0.1.0 -> 1.0.0)
npm run release:major

Required Secrets

• NPM_TOKEN: npm access token with publish permissions for @fortalece-ai scope

License

MIT