@clianta/sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to the Clianta SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-30
+
+### Added
+- Initial release of Clianta SDK
+- **Tracking & Analytics**
+  - Automatic page view tracking with SPA support
+  - Form tracking with auto-identification
+  - Scroll depth tracking (25%, 50%, 75%, 100%)
+  - Click tracking for buttons and CTAs
+  - User engagement detection
+  - File download tracking
+  - Exit intent detection
+  - JavaScript error tracking (optional plugin)
+  - Web Vitals and performance metrics (optional plugin)
+  - Offline event queue with automatic retry
+  - Event batching for efficient transmission
+  
+- **CRM API Client**
+  - Full CRUD operations for contacts
+  - Full CRUD operations for opportunities
+  - Opportunity stage management
+  - Authenticated API requests with token support
+  - Paginated list queries
+  - Type-safe API responses
+  
+- **Developer Experience**
+  - Full TypeScript support with type definitions
+  - Multiple build formats (UMD, ESM, CJS)
+  - Debug mode with verbose logging
+  - Plugin-based architecture
+  - Tree-shakeable exports
+  - Zero runtime dependencies
+  
+- **Privacy & Compliance**
+  - Consent management system
+  - Cookie-less tracking option
+  - Visitor ID persistence across sessions
+  - Session management with configurable timeout
+
+### Technical Details
+- SDK Version: 1.0.0
+- Build Formats: UMD (minified & unminified), ESM, CJS
+- TypeScript: Full type definitions included
+- Bundle Size: ~8KB gzipped (tracking only), ~12KB with CRM client
+- Browser Support: Modern browsers (ES2015+)
+- Node.js: 18.0.0+
+
+## [Unreleased]
+
+### Planned Features
+- Workflow automation helpers
+- Email campaign integration
+- Advanced analytics and reporting
+- Real-time notifications
+- Webhook management
+- Custom event validation
+- A/B testing support
+
+---
+
+## Migration Guide
+
+### From MorrisB SDK v3.x
+
+The Clianta SDK is a complete rebrand and enhancement of the MorrisB Tracking SDK.
+
+**Breaking Changes:**
+1. Package name changed from `@morrisb/tracker` to `@clianta/sdk`
+2. Global variable changed from `MorrisB` to `Clianta`
+3. Initialization function changed from `morrisb()` to `clianta()`
+4. Default API endpoint changed to `https://api.clianta.online`
+
+**Migration Steps:**
+
+```diff
+- import { morrisb } from '@morrisb/tracker';
++ import { clianta } from '@clianta/sdk';
+
+- const tracker = morrisb('workspace-id');
++ const tracker = clianta('workspace-id');
+```
+
+**New Features:**
+- CRM API client for managing contacts and opportunities
+- Enhanced TypeScript support
+- Improved error handling
+- Better offline support
+
+All tracking features remain compatible with the previous version.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clianta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# @clianta/sdk
+
+Professional CRM and tracking SDK for Clianta - Track visitors, manage contacts, opportunities, and analyze user behavior.
+
+## Features
+
+### Tracking & Analytics
+- **Page Views** - Automatic page view tracking with SPA support
+- **Form Tracking** - Auto-detect and track form interactions
+- **Scroll Depth** - Track scroll milestones (25%, 50%, 75%, 100%)
+- **Click Tracking** - Track button and CTA clicks
+- **User Engagement** - Detect active user engagement
+- **File Downloads** - Track file downloads
+- **Exit Intent** - Detect when users are about to leave
+- **Error Tracking** - Capture JavaScript errors (optional)
+- **Performance** - Web Vitals and page speed metrics (optional)
+- **Auto-Identify** - Automatically identify leads from form submissions
+- **Offline Support** - Queue events when offline, send when back
+
+### CRM API Client
+- **Contacts Management** - Full CRUD operations for contacts
+- **Opportunities Management** - Create, update, and track sales opportunities
+- **Authenticated Requests** - Secure API access with token authentication
+- **Type-Safe** - Full TypeScript support for all CRM operations
+
+### Developer Experience
+- **Debug Mode** - Verbose logging for troubleshooting
+- **TypeScript Support** - Full type definitions included
+- **Multiple Formats** - UMD, ESM, and CJS builds
+- **Tree-Shakeable** - Import only what you need
+- **Zero Dependencies** - Lightweight and fast
+
+## Installation
+
+### NPM
+
+```bash
+npm install @clianta/sdk
+```
+
+### Script Tag (CDN)
+
+```html
+<script src="https://unpkg.com/@clianta/sdk@1.0.0/dist/clianta.umd.min.js"></script>
+<script>
+  const tracker = Clianta.clianta('YOUR_WORKSPACE_ID');
+</script>
+```
+
+## Quick Start
+
+### Tracking
+
+```javascript
+import { clianta } from '@clianta/sdk';
+
+// Initialize tracker
+const tracker = clianta('YOUR_WORKSPACE_ID', {
+  debug: true,
+  apiEndpoint: 'https://api.clianta.online'
+});
+
+// Track custom event
+tracker.track('custom', 'Button Clicked', {
+  buttonId: 'signup-cta',
+  location: 'hero-section',
+});
+
+// Identify a visitor
+tracker.identify('john@example.com', {
+  firstName: 'John',
+  lastName: 'Doe',
+  company: 'Acme Inc',
+});
+
+// Manual page view (automatic by default)
+tracker.page('Pricing Page', {
+  plan: 'enterprise',
+});
+```
+
+### CRM API
+
+```javascript
+import { CRMClient } from '@clianta/sdk';
+
+// Initialize CRM client
+const crm = new CRMClient(
+  'https://api.clianta.online',
+  'YOUR_WORKSPACE_ID',
+  'YOUR_AUTH_TOKEN'
+);
+
+// Get all contacts
+const contacts = await crm.getContacts({
+  page: 1,
+  limit: 50,
+  status: 'lead'
+});
+
+// Create a new contact
+const newContact = await crm.createContact({
+  email: 'jane@example.com',
+  firstName: 'Jane',
+  lastName: 'Smith',
+  company: 'Tech Corp'
+});
+
+// Create an opportunity
+const opportunity = await crm.createOpportunity({
+  contactId: newContact.data._id,
+  pipelineId: 'pipeline-id',
+  stageId: 'stage-id',
+  title: 'Enterprise Deal',
+  value: 50000,
+  currency: 'USD'
+});
+
+// Update opportunity stage
+await crm.moveOpportunity(opportunity.data._id, 'new-stage-id');
+```
+
+## Configuration
+
+```typescript
+const tracker = clianta('YOUR_WORKSPACE_ID', {
+  // Backend API URL (auto-detected by default)
+  apiEndpoint: 'https://api.clianta.online',
+
+  // Enable debug logging
+  debug: false,
+
+  // Auto-track page views
+  autoPageView: true,
+
+  // Plugins to enable (default: all core plugins)
+  plugins: [
+    'pageView',
+    'forms',
+    'scroll',
+    'clicks',
+    'engagement',
+    'downloads',
+    'exitIntent',
+    // Optional:
+    // 'errors',
+    // 'performance',
+  ],
+
+  // Session timeout (default: 30 minutes)
+  sessionTimeout: 30 * 60 * 1000,
+
+  // Batch size before sending (default: 10)
+  batchSize: 10,
+
+  // Flush interval in ms (default: 5000)
+  flushInterval: 5000,
+});
+```
+
+## API Reference
+
+### Tracker Methods
+
+#### `tracker.track(eventType, eventName, properties?)`
+Track a custom event.
+
+#### `tracker.identify(email, traits?)`
+Identify a visitor and link to a contact.
+
+#### `tracker.page(name?, properties?)`
+Track a page view (automatic by default).
+
+#### `tracker.debug(enabled)`
+Enable or disable debug mode.
+
+#### `tracker.getVisitorId()`
+Get the current visitor ID.
+
+#### `tracker.getSessionId()`
+Get the current session ID.
+
+#### `tracker.flush()`
+Force send all queued events.
+
+#### `tracker.reset()`
+Reset visitor data (call on logout).
+
+### CRM Client Methods
+
+#### Contacts
+- `getContacts(params?)` - Get all contacts with pagination
+- `getContact(contactId)` - Get a single contact
+- `createContact(contact)` - Create a new contact
+- `updateContact(contactId, updates)` - Update a contact
+- `deleteContact(contactId)` - Delete a contact
+
+#### Opportunities
+- `getOpportunities(params?)` - Get all opportunities with pagination
+- `getOpportunity(opportunityId)` - Get a single opportunity
+- `createOpportunity(opportunity)` - Create a new opportunity
+- `updateOpportunity(opportunityId, updates)` - Update an opportunity
+- `deleteOpportunity(opportunityId)` - Delete an opportunity
+- `moveOpportunity(opportunityId, stageId)` - Move opportunity to a different stage
+
+## Framework Integration
+
+### React
+
+```tsx
+import { useEffect } from 'react';
+import { clianta } from '@clianta/sdk';
+
+function App() {
+  useEffect(() => {
+    const tracker = clianta('YOUR_WORKSPACE_ID', {
+      debug: process.env.NODE_ENV === 'development'
+    });
+
+    return () => {
+      tracker.flush();
+    };
+  }, []);
+
+  return <div>Your App</div>;
+}
+```
+
+### Next.js
+
+```tsx
+// app/layout.tsx or pages/_app.tsx
+import { clianta } from '@clianta/sdk';
+
+if (typeof window !== 'undefined') {
+  clianta('YOUR_WORKSPACE_ID');
+}
+```
+
+### Vue.js
+
+```vue
+<script setup>
+import { onMounted, onUnmounted } from 'vue';
+import { clianta } from '@clianta/sdk';
+
+let tracker;
+
+onMounted(() => {
+  tracker = clianta('YOUR_WORKSPACE_ID');
+});
+
+onUnmounted(() => {
+  tracker?.flush();
+});
+</script>
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes full type definitions:
+
+```typescript
+import type { 
+  TrackerCore, 
+  Contact, 
+  Opportunity,
+  ApiResponse 
+} from '@clianta/sdk';
+
+const tracker: TrackerCore = clianta('workspace-id');
+
+const response: ApiResponse<Contact> = await crm.getContact('contact-id');
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run build:watch
+
+# Run tests
+npm test
+
+# Type check
+npm run typecheck
+```
+
+## License
+
+MIT © Clianta
+
+## Support
+
+- Documentation: https://docs.clianta.online
+- Issues: https://github.com/xeet991fx/cliantaSDK/issues
+- Website: https://clianta.online