cuoral-ionic 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cuoral
+
+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,273 @@
+# Cuoral Ionic Library
+
+Proactive customer success platform integration for Ionic/Capacitor applications. Cuoral provides support ticketing, customer intelligence, screen recording, and comprehensive customer engagement tools.
+
+## Features
+
+✅ **Customer Support** - Integrated support ticketing system  
+✅ **Customer Intelligence** - Track and analyze customer behavior  
+✅ **Screen Recording** - Native iOS screen recording for issue reproduction  
+✅ **Modal Display** - Full-screen modal with floating chat button  
+✅ **TypeScript Support** - Full type definitions included  
+✅ **Simple API** - Just pass your public key and optional user info  
+✅ **Zero Configuration** - Everything handled automatically
+
+## Installation
+
+```bash
+npm install cuoral-ionic
+```
+
+After installing, sync your Capacitor project:
+
+```bash
+npx cap sync
+```
+
+### iOS Setup
+
+Add to your `Info.plist`:
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>We need access to your microphone to record audio with screen recordings</string>
+```
+
+## Quick Start
+
+### Option 1: Modal with Floating Button (Recommended)
+
+The easiest way to integrate Cuoral - displays a floating chat button that opens the widget in a full-screen modal.
+
+```typescript
+import { Component, OnInit, OnDestroy } from '@angular/core';
+import { Cuoral } from 'cuoral-ionic';
+
+@Component({
+  selector: 'app-home',
+  template: `
+    <ion-content>
+      <!-- Your app content -->
+      <h1>Welcome to Support</h1>
+
+      <!-- Optional: Custom button to open widget -->
+      <ion-button (click)="openSupport()"> Contact Support </ion-button>
+    </ion-content>
+  `,
+})
+export class HomePage implements OnInit, OnDestroy {
+  private cuoral: Cuoral;
+
+  constructor() {
+    this.cuoral = new Cuoral({
+      publicKey: 'your-public-key-here',
+      email: 'user@example.com', // Optional
+      firstName: 'John', // Optional
+      lastName: 'Doe', // Optional
+      showFloatingButton: true, // Show floating chat button
+      useModal: true, // Use modal display mode
+    });
+  }
+
+  ngOnInit() {
+    this.cuoral.initialize();
+  }
+
+  ngOnDestroy() {
+    this.cuoral.destroy();
+  }
+
+  // Open modal programmatically
+  openSupport() {
+    this.cuoral.openModal();
+  }
+}
+```
+
+**Features:**
+
+- 🎈 Floating blue chat button in bottom-right corner
+- 📱 Opens widget in full-screen modal with small margins
+- ❌ Close button in top-right
+- 🎨 Smooth animations and transitions
+- 🖱️ Click backdrop to close
+
+### Option 2: Embedded Iframe
+
+For more control over widget placement:
+
+```typescript
+import { Component, OnInit, OnDestroy } from '@angular/core';
+import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';
+import { Cuoral } from 'cuoral-ionic';
+
+@Component({
+  selector: 'app-support',
+  template: `
+    <ion-content>
+      <iframe [src]="widgetUrl" style="width: 100%; height: 600px; border: none;"> </iframe>
+    </ion-content>
+  `,
+})
+export class SupportPage implements OnInit, OnDestroy {
+  widgetUrl: SafeResourceUrl;
+  private cuoral: Cuoral;
+
+  constructor(private sanitizer: DomSanitizer) {
+    this.cuoral = new Cuoral({
+      publicKey: 'your-public-key-here',
+      useModal: false, // Disable modal mode
+    });
+
+    const url = this.cuoral.getWidgetUrl();
+    this.widgetUrl = this.sanitizer.bypassSecurityTrustResourceUrl(url);
+  }
+
+  ngOnInit() {
+    this.cuoral.initialize();
+  }
+
+  ngOnDestroy() {
+    this.cuoral.destroy();
+  }
+}
+```
+
+## Configuration
+
+### CuoralOptions
+
+```typescript
+interface CuoralOptions {
+  publicKey: string; // Required: Your Cuoral public key
+  email?: string; // Optional: User email
+  firstName?: string; // Optional: User first name
+  lastName?: string; // Optional: User last name
+  debug?: boolean; // Optional: Enable debug logging (default: false)
+  widgetBaseUrl?: string; // Optional: Custom widget URL (default: CDN)
+  showFloatingButton?: boolean; // Optional: Show floating chat button (default: true)
+  useModal?: boolean; // Optional: Use modal display mode (default: true)
+}
+```
+
+### Widget URL
+
+By default, the widget loads from `https://js.cuoral.com/mobile.html` (production CDN).
+
+**Production (Default):**
+
+```typescript
+new Cuoral({ publicKey: 'your-key' });
+```
+
+**Custom URL (Optional):**
+
+If you need to use a custom widget URL for testing or self-hosting:
+
+```typescript
+new Cuoral({
+  publicKey: 'your-key',
+  widgetBaseUrl: 'https://your-domain.com/mobile.html',
+});
+```
+
+## API Reference
+
+### Cuoral Methods
+
+```typescript
+// Initialize Cuoral
+cuoral.initialize(): void
+
+// Get widget URL for iframe embedding
+cuoral.getWidgetUrl(): string
+
+// Open modal programmatically
+cuoral.openModal(): void
+
+// Close modal programmatically
+cuoral.closeModal(): void
+
+// Check if modal is open
+cuoral.isModalOpen(): boolean
+
+// Clean up resources
+cuoral.destroy(): void
+```
+
+## What Gets Handled Automatically
+
+- ✅ Support ticket creation and management
+- ✅ Customer intelligence tracking
+- ✅ Screen recording start/stop
+- ✅ File path conversion for video playback
+- ✅ Communication between widget and native code
+- ✅ Video upload to Cuoral backend
+- ✅ State management
+- ✅ Permissions handling
+
+## Troubleshooting
+
+### Recording doesn't start
+
+**Check iOS permissions:**
+
+- Verify `NSMicrophoneUsageDescription` is in Info.plist
+- System will prompt user automatically on first recording
+
+**Enable debug mode:**
+
+```typescript
+new Cuoral({
+  publicKey: 'your-key',
+  debug: true, // See console logs
+});
+```
+
+### Widget not appearing
+
+**Modal mode:**
+
+- Make sure you called `cuoral.initialize()`
+- Check that `useModal: true` is set (default)
+- Look for the blue floating button in bottom-right
+
+**Iframe mode:**
+
+- Verify `widgetUrl` is properly sanitized with `DomSanitizer`
+- Check browser console for CORS errors
+- Ensure iframe has proper dimensions in CSS
+
+### Build errors
+
+**iOS Pod Issues:**
+
+```bash
+cd ios
+pod deintegrate
+pod install
+cd ..
+npx cap sync ios
+```
+
+**Clean build:**
+
+```bash
+rm -rf node_modules dist
+npm install
+npx cap sync
+```
+
+## Support
+
+- 📧 Email: support@cuoral.com
+- 📖 Docs: https://docs.cuoral.com
+- 🐛 Issues: https://github.com/cuoral/cuoral-ionic/issues
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file
+
+---
+
+Built with ❤️ by Cuoral

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.cuoral.ionic">
+    
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" 
+                     android:maxSdkVersion="28" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    
+</manifest>

package/android/src/main/java/com/cuoral/ionic/CuoralPlugin.java

@@ -0,0 +1,291 @@
+package com.cuoral.ionic;
+
+import android.Manifest;
+import android.app.Activity;
+import android.content.Context;
+import android.content.Intent;
+import android.content.pm.PackageManager;
+import android.graphics.Bitmap;
+import android.media.MediaRecorder;
+import android.media.projection.MediaProjection;
+import android.media.projection.MediaProjectionManager;
+import android.os.Build;
+import android.util.Base64;
+import android.util.DisplayMetrics;
+import android.view.View;
+
+import androidx.core.app.ActivityCompat;
+import androidx.core.content.ContextCompat;
+
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import com.getcapacitor.annotation.Permission;
+import com.getcapacitor.annotation.ActivityCallback;
+
+import java.io.ByteArrayOutputStream;
+import java.io.File;
+import java.io.IOException;
+
+@CapacitorPlugin(name = "CuoralPlugin", permissions = {
+        @Permission(strings = { Manifest.permission.RECORD_AUDIO }, alias = "audio"),
+        @Permission(strings = { Manifest.permission.WRITE_EXTERNAL_STORAGE }, alias = "storage")
+})
+public class CuoralPlugin extends Plugin {
+
+    private static final int SCREEN_CAPTURE_REQUEST_CODE = 1001;
+    private static final int PERMISSION_REQUEST_CODE = 1002;
+
+    private MediaProjectionManager projectionManager;
+    private MediaProjection mediaProjection;
+    private MediaRecorder mediaRecorder;
+    private boolean isRecording = false;
+    private long recordingStartTime = 0;
+    private String videoFilePath;
+    private PluginCall currentCall;
+
+    @Override
+    public void load() {
+        super.load();
+        projectionManager = (MediaProjectionManager) getContext()
+                .getSystemService(Context.MEDIA_PROJECTION_SERVICE);
+    }
+
+    @PluginMethod
+    public void startRecording(PluginCall call) {
+        if (isRecording) {
+            call.resolve(createErrorResult("Already recording"));
+            return;
+        }
+
+        // Save call for later use
+        currentCall = call;
+
+        // Check if we need audio permission
+        boolean includeAudio = call.getBoolean("includeAudio", false);
+        if (includeAudio && !hasAudioPermission()) {
+            requestPermissionForAlias("audio", call, "audioPermissionCallback");
+            return;
+        }
+
+        // Request screen capture
+        Intent captureIntent = projectionManager.createScreenCaptureIntent();
+        startActivityForResult(call, captureIntent, "screenCaptureCallback");
+    }
+
+    @ActivityCallback
+    private void screenCaptureCallback(PluginCall call, com.getcapacitor.PluginResult result) {
+        if (result.getResultCode() != Activity.RESULT_OK) {
+            call.reject("Screen capture permission denied");
+            return;
+        }
+
+        Intent data = result.getData();
+        mediaProjection = projectionManager.getMediaProjection(result.getResultCode(), data);
+
+        // Setup media recorder
+        boolean includeAudio = call.getBoolean("includeAudio", false);
+        float quality = call.getFloat("quality", 1.0f);
+
+        try {
+            setupMediaRecorder(includeAudio, quality);
+            mediaRecorder.start();
+            isRecording = true;
+            recordingStartTime = System.currentTimeMillis();
+
+            JSObject ret = new JSObject();
+            ret.put("success", true);
+            call.resolve(ret);
+
+            // Notify listeners
+            JSObject eventData = new JSObject();
+            eventData.put("timestamp", recordingStartTime);
+            notifyListeners("recordingStarted", eventData);
+
+        } catch (Exception e) {
+            call.reject("Failed to start recording: " + e.getMessage());
+        }
+    }
+
+    @ActivityCallback
+    private void audioPermissionCallback(PluginCall call) {
+        if (!hasAudioPermission()) {
+            call.reject("Audio permission required");
+            return;
+        }
+        // Retry starting recording
+        startRecording(call);
+    }
+
+    @PluginMethod
+    public void stopRecording(PluginCall call) {
+        if (!isRecording) {
+            call.resolve(createErrorResult("Not recording"));
+            return;
+        }
+
+        try {
+            mediaRecorder.stop();
+            mediaRecorder.reset();
+            mediaRecorder.release();
+            mediaRecorder = null;
+
+            if (mediaProjection != null) {
+                mediaProjection.stop();
+                mediaProjection = null;
+            }
+
+            isRecording = false;
+            long duration = (System.currentTimeMillis() - recordingStartTime) / 1000;
+
+            JSObject ret = new JSObject();
+            ret.put("success", true);
+            ret.put("filePath", videoFilePath);
+            ret.put("duration", duration);
+            call.resolve(ret);
+
+            // Notify listeners
+            JSObject eventData = new JSObject();
+            eventData.put("filePath", videoFilePath);
+            eventData.put("duration", duration);
+            notifyListeners("recordingStopped", eventData);
+
+        } catch (Exception e) {
+            call.reject("Failed to stop recording: " + e.getMessage());
+        }
+    }
+
+    @PluginMethod
+    public void getRecordingState(PluginCall call) {
+        long duration = isRecording ? (System.currentTimeMillis() - recordingStartTime) / 1000 : 0;
+
+        JSObject ret = new JSObject();
+        ret.put("isRecording", isRecording);
+        ret.put("duration", duration);
+        ret.put("filePath", videoFilePath != null ? videoFilePath : "");
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void takeScreenshot(PluginCall call) {
+        try {
+            Activity activity = getActivity();
+            View rootView = activity.getWindow().getDecorView().getRootView();
+            rootView.setDrawingCacheEnabled(true);
+
+            Bitmap bitmap = Bitmap.createBitmap(rootView.getDrawingCache());
+            rootView.setDrawingCacheEnabled(false);
+
+            // Get options
+            float quality = call.getFloat("quality", 0.92f);
+            String format = call.getString("format", "png");
+
+            // Convert to base64
+            ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
+            if (format.equals("jpeg")) {
+                bitmap.compress(Bitmap.CompressFormat.JPEG, (int) (quality * 100), outputStream);
+            } else {
+                bitmap.compress(Bitmap.CompressFormat.PNG, 100, outputStream);
+            }
+
+            byte[] bytes = outputStream.toByteArray();
+            String base64 = Base64.encodeToString(bytes, Base64.NO_WRAP);
+
+            JSObject ret = new JSObject();
+            ret.put("base64", base64);
+            ret.put("mimeType", "image/" + format);
+            ret.put("width", bitmap.getWidth());
+            ret.put("height", bitmap.getHeight());
+            call.resolve(ret);
+
+            // Notify listeners
+            JSObject eventData = new JSObject();
+            eventData.put("success", true);
+            notifyListeners("screenshotTaken", eventData);
+
+            bitmap.recycle();
+
+        } catch (Exception e) {
+            call.reject("Failed to take screenshot: " + e.getMessage());
+        }
+    }
+
+    @PluginMethod
+    public void isRecordingSupported(PluginCall call) {
+        JSObject ret = new JSObject();
+        ret.put("supported", Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP);
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void requestPermissions(PluginCall call) {
+        if (hasRequiredPermissions()) {
+            JSObject ret = new JSObject();
+            ret.put("granted", true);
+            call.resolve(ret);
+        } else {
+            requestAllPermissions(call, "permissionsCallback");
+        }
+    }
+
+    @ActivityCallback
+    private void permissionsCallback(PluginCall call) {
+        JSObject ret = new JSObject();
+        ret.put("granted", hasRequiredPermissions());
+        call.resolve(ret);
+    }
+
+    // Helper methods
+
+    private void setupMediaRecorder(boolean includeAudio, float quality) throws IOException {
+        DisplayMetrics metrics = getContext().getResources().getDisplayMetrics();
+
+        File outputDir = getContext().getFilesDir();
+        videoFilePath = new File(outputDir, "cuoral_recording_" + System.currentTimeMillis() + ".mp4")
+                .getAbsolutePath();
+
+        mediaRecorder = new MediaRecorder();
+
+        if (includeAudio) {
+            mediaRecorder.setAudioSource(MediaRecorder.AudioSource.MIC);
+        }
+        mediaRecorder.setVideoSource(MediaRecorder.VideoSource.SURFACE);
+        mediaRecorder.setOutputFormat(MediaRecorder.OutputFormat.MPEG_4);
+        mediaRecorder.setOutputFile(videoFilePath);
+
+        int bitRate = (int) (6000000 * quality); // Base bitrate 6Mbps
+        mediaRecorder.setVideoEncoder(MediaRecorder.VideoEncoder.H264);
+        mediaRecorder.setVideoSize(metrics.widthPixels, metrics.heightPixels);
+        mediaRecorder.setVideoFrameRate(30);
+        mediaRecorder.setVideoEncodingBitRate(bitRate);
+
+        if (includeAudio) {
+            mediaRecorder.setAudioEncoder(MediaRecorder.AudioEncoder.AAC);
+            mediaRecorder.setAudioEncodingBitRate(128000);
+            mediaRecorder.setAudioSamplingRate(44100);
+        }
+
+        mediaRecorder.prepare();
+    }
+
+    private boolean hasAudioPermission() {
+        return ContextCompat.checkSelfPermission(getContext(),
+                Manifest.permission.RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED;
+    }
+
+    private boolean hasRequiredPermissions() {
+        return hasAudioPermission() &&
+                (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q ||
+                        ContextCompat.checkSelfPermission(getContext(),
+                                Manifest.permission.WRITE_EXTERNAL_STORAGE) == PackageManager.PERMISSION_GRANTED);
+    }
+
+    private JSObject createErrorResult(String message) {
+        JSObject ret = new JSObject();
+        ret.put("success", false);
+        ret.put("error", message);
+        return ret;
+    }
+}

package/dist/bridge.d.ts

@@ -0,0 +1,51 @@
+import { CuoralMessage, CuoralMessageType, CuoralConfig } from './types';
+/**
+ * Bridge for bidirectional communication between WebView and Native code
+ */
+export declare class CuoralBridge {
+    private config;
+    private messageHandlers;
+    private isInitialized;
+    private widgetIframe;
+    constructor(config: CuoralConfig);
+    /**
+     * Initialize the bridge
+     */
+    initialize(): void;
+    /**
+     * Send message to native code
+     */
+    sendToNative(message: CuoralMessage): void;
+    /**
+     * Send message to widget iframe
+     */
+    sendToWidget(message: CuoralMessage): void;
+    /**
+     * Register message handler
+     */
+    on(type: CuoralMessageType, handler: (payload: any) => void): () => void;
+    /**
+     * Setup window message listener
+     */
+    private setupMessageListener;
+    /**
+     * Debug logging
+     */
+    private log;
+    /**
+     * Destroy the bridge
+     */
+    destroy(): void;
+}
+declare global {
+    interface Window {
+        webkit?: {
+            messageHandlers?: {
+                cuoral?: {
+                    postMessage: (message: any) => void;
+                };
+            };
+        };
+    }
+}
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEzE;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,eAAe,CAAoE;IAC3F,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,YAAY,CAAkC;gBAE1C,MAAM,EAAE,YAAY;IAKhC;;OAEG;IACI,UAAU,IAAI,IAAI;IAgBzB;;OAEG;IACI,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAoBjD;;OAEG;IACI,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAyCjD;;OAEG;IACI,EAAE,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,GAAG,MAAM,IAAI;IAmB/E;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAqC5B;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACI,OAAO,IAAI,IAAI;CAKvB;AAGD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,MAAM,CAAC,EAAE;YACP,eAAe,CAAC,EAAE;gBAChB,MAAM,CAAC,EAAE;oBACP,WAAW,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;iBACrC,CAAC;aACH,CAAC;SACH,CAAC;KACH;CACF"}