npm package: @pedrohrs/deep-service-desk-widget
Description: Widget Vue.js para integração com o sistema Deep Service Desk - Versão limpa sem console.logs - Compatível com Vue 2.7.16 e Vue 3 - Com botão flutuante automático
Author: Pedro Henrique
Latest version: 1.3.8

# Deep Service Desk Widget

Widget Vue.js para integração com o sistema Deep Service Desk. Compatível com Vue 2.7.16 e Vue 3, oferece uma interface moderna e responsiva para criação de tickets de suporte.

## 📋 Índice

- [Características](#características)
- [Instalação](#instalação)
- [Configuração](#configuração)
- [Uso Básico](#uso-básico)
- [Componentes Disponíveis](#componentes-disponíveis)
- [API e Métodos](#api-e-métodos)
- [Eventos](#eventos)
- [Personalização](#personalização)
- [Exemplos](#exemplos)
- [Troubleshooting](#troubleshooting)

## ✨ Características

- 🎯 **Compatibilidade**: Vue 2.7.16 e Vue 3
- 🎨 **Interface Moderna**: Design responsivo e intuitivo
- 🔄 **Botão Flutuante**: Botão automático para abertura de tickets
- 📱 **Responsivo**: Funciona perfeitamente em desktop e mobile
- 🔧 **Configurável**: Múltiplas opções de configuração
- 🌐 **Independente**: Funciona mesmo sem Vue (fallback HTML)
- 🔔 **Notificações**: Sistema de notificações toast integrado
- 🔒 **Seguro**: Validação de dados e tratamento de erros

## 📦 Instalação

### Via NPM (Recomendado)

```bash
npm install @pedrohrs/deep-service-desk-widget
```

### Via Yarn

```bash
yarn add @pedrohrs/deep-service-desk-widget
```

### Via CDN

```html
<!-- CSS -->
<link rel="stylesheet" href="https://unpkg.com/@pedrohrs/deep-service-desk-widget/dist/deep-service-desk-widget.css">

<!-- JavaScript -->
<script src="https://unpkg.com/@pedrohrs/deep-service-desk-widget/dist/deep-service-desk-widget.umd.min.js"></script>
```

## ⚙️ Configuração

### Vue 3

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import DeepServiceDeskPlugin from '@pedrohrs/deep-service-desk-widget'

const app = createApp(App)

// Configuração do plugin
app.use(DeepServiceDeskPlugin, {
  apiUrl: 'https://sua-api.com/api',
  clientUuid: 'seu-client-uuid-aqui', // OBRIGATÓRIO
  showFloatingButton: true // Opcional, padrão: true
})

app.mount('#app')
```

### Vue 2.7.16

```javascript
import Vue from 'vue'
import App from './App.vue'
import DeepServiceDeskPlugin from '@pedrohrs/deep-service-desk-widget'

// Configuração do plugin
Vue.use(DeepServiceDeskPlugin, {
  apiUrl: 'https://sua-api.com/api',
  clientUuid: 'seu-client-uuid-aqui', // OBRIGATÓRIO
  showFloatingButton: true // Opcional, padrão: true
})

new Vue({
  render: h => h(App)
}).$mount('#app')
```

### Configuração via CDN

```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/@pedrohrs/deep-service-desk-widget/dist/deep-service-desk-widget.css">
</head>
<body>
  <div id="app"></div>
  
  <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
  <script src="https://unpkg.com/@pedrohrs/deep-service-desk-widget/dist/deep-service-desk-widget.umd.min.js"></script>
  
  <script>
    const { createApp } = Vue
    
    createApp({}).use(DeepServiceDeskPlugin, {
      apiUrl: 'https://sua-api.com/api',
      clientUuid: 'seu-client-uuid-aqui'
    }).mount('#app')
  </script>
</body>
</html>
```

## 🚀 Uso Básico

### Configuração Automática (Recomendado)

Após instalar o plugin, um botão flutuante aparecerá automaticamente no canto inferior direito da página. Os usuários podem clicar nele para abrir o formulário de criação de tickets.

### Uso Manual dos Componentes

```vue
<template>
  <div>
    <!-- Widget completo de tickets -->
    <TicketWidget 
      :api-url="apiUrl"
      :client-uuid="clientUuid"
      @ticket-created="onTicketCreated"
      @ticket-error="onTicketError"
    />
    
    <!-- Ou use o widget flutuante -->
    <FloatingTicketWidget />
    
    <!-- Botão personalizado para abrir o widget -->
    <button @click="openTicket">Abrir Suporte</button>
  </div>
</template>

<script>
export default {
  data() {
    return {
      apiUrl: 'https://sua-api.com/api',
      clientUuid: 'seu-client-uuid-aqui'
    }
  },
  methods: {
    openTicket() {
      // Dispara o evento para abrir o widget
      this.$deepServiceDeskButton.openTicket()
    },
    onTicketCreated(ticketData) {
      console.log('Ticket criado:', ticketData)
    },
    onTicketError(error) {
      console.error('Erro ao criar ticket:', error)
    }
  }
}
</script>
```

## 🧩 Componentes Disponíveis

### TicketWidget

Componente principal que exibe o formulário de criação de tickets em um modal.

**Props:**
- `apiUrl` (String): URL da API do Deep Service Desk
- `clientUuid` (String): UUID do cliente (obrigatório)

**Eventos:**
- `@ticket-created`: Emitido quando um ticket é criado com sucesso
- `@ticket-error`: Emitido quando ocorre um erro na criação

### FloatingTicketWidget

Componente que gerencia o widget de ticket de forma invisível, usado internamente pelo botão flutuante.

## 🔧 API e Métodos

### Métodos Globais

Após instalar o plugin, os seguintes métodos ficam disponíveis:

```javascript
// Vue 3
this.$deepServiceDeskButton.showFloatingButton()
this.$deepServiceDeskButton.hideFloatingButton()
this.$deepServiceDeskButton.openTicket()

// Vue 2
this.$deepServiceDeskButton.showFloatingButton()
this.$deepServiceDeskButton.hideFloatingButton()
this.$deepServiceDeskButton.openTicket()
```

### Configuração Global

```javascript
// Acessar configuração global
console.log(this.$deepServiceDesk)

// Vue 3 - via inject
export default {
  inject: ['deepServiceDeskConfig'],
  mounted() {
    console.log(this.deepServiceDeskConfig)
  }
}
```

## 📡 Eventos

### Eventos do Window

O widget emite eventos globais que podem ser escutados:

```javascript
// Evento disparado quando um ticket é criado
window.addEventListener('ticket-created', (event) => {
  console.log('Ticket criado:', event.detail)
})

// Evento disparado quando ocorre erro
window.addEventListener('ticket-error', (event) => {
  console.log('Erro:', event.detail)
})

// Evento para abrir o widget programaticamente
window.dispatchEvent(new CustomEvent('new-ticket'))
```

## 🎨 Personalização

### Variáveis de Ambiente

O widget suporta configuração via variáveis de ambiente:

```bash
# .env
VITE_API_URL=https://sua-api.com/api
VITE_CLIENT_UUID=seu-client-uuid-aqui

# Para Vue CLI
VUE_APP_API_URL=https://sua-api.com/api
VUE_APP_CLIENT_UUID=seu-client-uuid-aqui
```

### Configuração via Window

```javascript
// Definir configurações globais
window.DEEP_SERVICE_DESK_API_URL = 'https://sua-api.com/api'
window.DEEP_SERVICE_DESK_CLIENT_UUID = 'seu-client-uuid-aqui'
```

### Estilos CSS

O widget inclui estilos padrão, mas você pode personalizá-los:

```css
/* Personalizar o botão flutuante */
#deep-service-desk-floating-btn {
  background: linear-gradient(135deg, #your-color 0%, #your-color-2 100%) !important;
  bottom: 30px !important;
  right: 30px !important;
}

/* Personalizar o modal */
.popup-overlay {
  background-color: rgba(0, 0, 0, 0.8) !important;
}

.popup-content {
  border-radius: 12px !important;
  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.3) !important;
}
```

## 📚 Exemplos

### Exemplo Completo - Vue 3

```vue
<template>
  <div id="app">
    <h1>Minha Aplicação</h1>
    
    <!-- O botão flutuante aparece automaticamente -->
    
    <!-- Botão personalizado opcional -->
    <button @click="abrirSuporte" class="btn-suporte">
      Precisa de Ajuda?
    </button>
  </div>
</template>

<script>
export default {
  name: 'App',
  mounted() {
    // Escutar eventos do widget
    window.addEventListener('ticket-created', this.onTicketCriado)
    window.addEventListener('ticket-error', this.onTicketErro)
  },
  beforeUnmount() {
    window.removeEventListener('ticket-created', this.onTicketCriado)
    window.removeEventListener('ticket-error', this.onTicketErro)
  },
  methods: {
    abrirSuporte() {
      this.$deepServiceDeskButton.openTicket()
    },
    onTicketCriado(event) {
      console.log('Ticket criado com sucesso:', event.detail)
      // Aqui você pode implementar lógica adicional
    },
    onTicketErro(event) {
      console.error('Erro ao criar ticket:', event.detail)
      // Aqui você pode implementar tratamento de erro
    }
  }
}
</script>
```

### Exemplo com Configuração Dinâmica

```vue
<template>
  <div>
    <button @click="configurarWidget">Configurar Widget</button>
    <button @click="mostrarBotao">Mostrar Botão</button>
    <button @click="esconderBotao">Esconder Botão</button>
  </div>
</template>

<script>
export default {
  methods: {
    configurarWidget() {
      // Reconfigurar o widget dinamicamente
      this.$deepServiceDesk.clientUuid = 'novo-uuid'
      this.$deepServiceDesk.apiUrl = 'https://nova-api.com/api'
    },
    mostrarBotao() {
      this.$deepServiceDeskButton.showFloatingButton()
    },
    esconderBotao() {
      this.$deepServiceDeskButton.hideFloatingButton()
    }
  }
}
</script>
```

### Exemplo sem Vue (HTML Puro)

```html
<!DOCTYPE html>
<html>
<head>
  <title>Widget sem Vue</title>
  <link rel="stylesheet" href="https://unpkg.com/@pedrohrs/deep-service-desk-widget/dist/deep-service-desk-widget.css">
</head>
<body>
  <h1>Minha Página</h1>
  <button onclick="abrirTicket()">Abrir Suporte</button>
  
  <script src="https://unpkg.com/@pedrohrs/deep-service-desk-widget/dist/deep-service-desk-widget.umd.min.js"></script>
  <script>
    // Configurar o widget
    window.DEEP_SERVICE_DESK_API_URL = 'https://sua-api.com/api'
    window.DEEP_SERVICE_DESK_CLIENT_UUID = 'seu-client-uuid-aqui'
    
    // Função para abrir ticket
    function abrirTicket() {
      window.dispatchEvent(new CustomEvent('new-ticket'))
    }
    
    // Escutar eventos
    window.addEventListener('ticket-created', (event) => {
      alert('Ticket criado: ' + event.detail.id)
    })
  </script>
</body>
</html>
```

## 🔍 Troubleshooting

### Problemas Comuns

#### 1. "clientUuid é obrigatório"

**Erro:** `Deep Service Desk Widget: clientUuid é obrigatório na configuração`

**Solução:** Certifique-se de fornecer o `clientUuid` na configuração:

```javascript
app.use(DeepServiceDeskPlugin, {
  clientUuid: 'seu-client-uuid-aqui' // OBRIGATÓRIO
})
```

#### 2. Botão flutuante não aparece

**Possíveis causas:**
- `showFloatingButton` está definido como `false`
- Erro de JavaScript impedindo a inicialização
- Conflito de CSS

**Solução:**
```javascript
// Verificar configuração
console.log(this.$deepServiceDesk)

// Mostrar botão manualmente
this.$deepServiceDeskButton.showFloatingButton()
```

#### 3. Formulário não envia

**Possíveis causas:**
- URL da API incorreta
- Problemas de CORS
- Cliente UUID inválido

**Solução:**
```javascript
// Verificar configuração
console.log('API URL:', this.$deepServiceDesk.apiUrl)
console.log('Client UUID:', this.$deepServiceDesk.clientUuid)

// Verificar console do navegador para erros de rede
```

#### 4. Incompatibilidade com Vue 2

**Erro:** Plugin não funciona com Vue 2

**Solução:** Certifique-se de usar Vue 2.7.16 ou superior:

```bash
npm install vue@^2.7.16
```

### Debug

Para ativar logs detalhados, abra o console do navegador. O widget emite logs informativos que ajudam no debug:

```javascript
// Logs do widget começam com emojis:
// 🚀 Instalação do plugin
// 🔧 Configuração
// ✅ Sucesso
// ⚠️ Avisos
// ❌ Erros
```

## 📄 Licença

MIT License - veja o arquivo LICENSE para detalhes.

## 🤝 Contribuição

Contribuições são bem-vindas! Por favor, abra uma issue ou pull request no repositório.

## 📞 Suporte

Para suporte técnico, abra uma issue no [repositório GitHub](https://github.com/pedrohrs/deep-service-desk-widget/issues).