zdata-client/README.md

TypeScript client library for zdata backend API with authentication and full CRUD operations

# ZData Client v2.0.0

Uma biblioteca TypeScript client simplificada para acesso à API do ZData backend com autenticação e operações CRUD completas.

## 🚀 Nova Arquitetura Simplificada

A versão 2.0 foi completamente refatorada para uma API mais simples e direta:

- ✅ **Funções de autenticação standalone** (não classes)
- ✅ **ResourceRepository** aceita access_token diretamente
- ✅ **Sem gerenciamento de localStorage**
- ✅ **Foco apenas em acesso à API**
- ✅ **Controle total do usuário sobre tokens**

## 📦 Instalação

```bash
npm install zdata-client
```

## 🔑 Autenticação

### Login

```typescript
import { login } from 'zdata-client';

const authResponse = await login(
  'https://api.example.com',  // baseUrl
  'workspace-id',             // workspaceId
  {
    email: 'user@example.com',
    password: 'password123'
  }
);

console.log(authResponse.access_token);
console.log(authResponse.user);
```

### Registro

```typescript
import { register } from 'zdata-client';

const authResponse = await register(
  'https://api.example.com',  // baseUrl
  'workspace-id',             // workspaceId
  {
    name: 'João Silva',
    email: 'joao@example.com',
    password: 'password123'
  }
);

console.log(authResponse.access_token);
```

## 🗄️ Operações CRUD

### Usando ResourceRepository

```typescript
import { ResourceRepository } from 'zdata-client';

// Criar repositório com token de autenticação
const repository = new ResourceRepository(
  'https://api.example.com',  // baseUrl
  'workspace-id',             // workspaceId
  'your-access-token',        // accessToken
  5000                        // timeout (opcional)
);

// Criar registro
const newUser = await repository.createRecord('users', {
  name: 'Maria Silva',
  email: 'maria@example.com'
});

// Buscar por ID
const user = await repository.findRecordById('users', 'user-id');

// Buscar com paginação
const users = await repository.findRecords({
  resourceName: 'users',
  page: 1,
  limit: 10,
  search: 'maria'
});

// Atualizar
const updatedUser = await repository.updateRecord('users', 'user-id', {
  name: 'Maria Santos'
});

// Deletar
await repository.deleteRecord('users', 'user-id');
```

### Usando Factory Function

```typescript
import { createRepository } from 'zdata-client';

const repository = createRepository(
  'https://api.example.com',
  'workspace-id', 
  'access-token'
);

const users = await repository.findRecords({
  resourceName: 'users',
  page: 1
});
```

## 👤 Operações do Usuário Logado

A biblioteca fornece o `LoggedUserClient` para operações específicas do usuário autenticado:

```typescript
import { LoggedUserClient } from 'zdata-client';

// Criar cliente com token de autenticação
const userClient = new LoggedUserClient(
  'https://api.example.com',  // baseUrl
  'workspace-id',             // workspaceId
  'your-access-token',        // accessToken
  5000                        // timeout (opcional)
);

// Obter perfil do usuário
const profile = await userClient.getProfile();
console.log(profile);
// Output:
// {
//   id: "ef4c8d10-582c-4bd6-bf56-7409efac7617",
//   name: "Adriano Delvoux SubUser", 
//   email: "adrianodelvoux+teste001@gmail.com",
//   settings: {
//     themeMode: "light"
//   }
// }

// Atualizar nome do usuário
const updated = await userClient.updateProfile({
  name: 'Novo Nome'
});

// Alterar tema para modo escuro
const darkMode = await userClient.updateProfile({
  themeMode: 'dark'
});

// Atualizar múltiplos campos
const multiUpdate = await userClient.updateProfile({
  name: 'João Silva',
  themeMode: 'light'
});

// Limpar campos (definir como null)
const cleared = await userClient.updateProfile({
  name: null,
  themeMode: 'dark'
});
```

### Tipos do LoggedUserClient

```typescript
import type { LoggedUser, UpdateLoggedUser } from 'zdata-client';

// Tipo de resposta do perfil
const profile: LoggedUser = {
  id: string;
  name: string;
  email: string;
  settings: {
    themeMode: 'light' | 'dark';
  };
};

// Tipo para atualização (todos os campos são opcionais)
const updateData: UpdateLoggedUser = {
  name?: string | null;
  themeMode?: 'light' | 'dark' | null;
};
```

## 🎯 Uso Completo (Login + CRUD + Perfil)

```typescript
import { login, ResourceRepository, LoggedUserClient } from 'zdata-client';

const baseUrl = 'https://api.example.com';
const workspaceId = 'my-workspace';

// 1. Fazer login
const authResponse = await login(baseUrl, workspaceId, {
  email: 'user@example.com',
  password: 'password123'
});

// 2. Criar repositório com token
const repository = new ResourceRepository(
  baseUrl,
  workspaceId,
  authResponse.access_token
);

// 3. Criar cliente do usuário logado
const userClient = new LoggedUserClient(
  baseUrl,
  workspaceId,
  authResponse.access_token
);

// 4. Obter perfil do usuário
const profile = await userClient.getProfile();
console.log(`Olá, ${profile.name}! Tema atual: ${profile.settings.themeMode}`);

// 5. Usar o repositório para operações CRUD
const users = await repository.findRecords({
  resourceName: 'users',
  page: 1,
  limit: 10
});

console.log(`Found ${users.meta.totalRecords} users`);

// 6. Atualizar perfil se necessário
if (profile.settings.themeMode === 'light') {
  await userClient.updateProfile({ themeMode: 'dark' });
  console.log('Tema alterado para escuro!');
}
```

## 🏗️ Classes de Repositório Tipadas

Para casos mais avançados, você pode criar classes tipadas que herdam de `BaseDataSourceClient`:

```typescript
import { BaseDataSourceClient, type CreateEntity, type EntityWithBase } from 'zdata-client';

interface User {
  name: string;
  email: string;
  role: string;
}

class UserRepository extends BaseDataSourceClient<User> {
  constructor(baseUrl: string, workspaceId: string, accessToken: string) {
    super(baseUrl, workspaceId, accessToken, 'users');
  }

  // Métodos customizados
  async findByRole(role: string) {
    return this.find({ search: `role:${role}` });
  }

  async createAdmin(userData: CreateEntity<User>) {
    return this.create({ ...userData, role: 'admin' });
  }
}

// Uso
const userRepo = new UserRepository(baseUrl, workspaceId, accessToken);
const admins = await userRepo.findByRole('admin');
```

## 📝 Tipos TypeScript

A biblioteca fornece tipos completos para TypeScript:

```typescript
import type {
  LoginRequest,
  RegisterRequest, 
  AuthResponse,
  FindRecordsParams,
  PaginatedResponse,
  BaseEntity,
  LoggedUser,
  UpdateLoggedUser
} from 'zdata-client';

// Exemplo de uso com tipos
const params: FindRecordsParams = {
  resourceName: 'products',
  page: 1,
  limit: 20,
  search: 'electronics'
};

const response: PaginatedResponse<Product> = await repository.findRecords(params);
```

## 🔄 Migração da v1.x

### Antes (v1.x):
```typescript
const client = new ZDataClient({
  baseUrl: 'https://api.example.com',
  workspaceId: 'workspace-id',
  enableCache: true
});

await client.login({ email: 'user@example.com', password: 'pass' });
const users = await client.findRecords({ resourceName: 'users' });
```

### Agora (v2.0):
```typescript
// 1. Login separado
const auth = await login('https://api.example.com', 'workspace-id', {
  email: 'user@example.com', 
  password: 'pass'
});

// 2. Repositório com token
const repository = new ResourceRepository(
  'https://api.example.com',
  'workspace-id',
  auth.access_token
);

const users = await repository.findRecords({ resourceName: 'users' });
```

## 🛠️ Recursos Removidos na v2.0

- ❌ Classe `ZDataClient` (substituída por funções e repositório)
- ❌ Classe `AuthService` (substituída por funções `login`/`register`)
- ❌ Cache interno automático (usuário implementa externamente se necessário)
- ❌ Gerenciamento de localStorage/sessionStorage
- ❌ Configuração complexa com múltiplas opções

## 🎯 Benefícios da v2.0

- ✅ **API mais simples**: Funções diretas em vez de classes complexas
- ✅ **Controle total**: Usuário gerencia tokens como preferir
- ✅ **Menor acoplamento**: Cada peça funciona independentemente  
- ✅ **Mais testável**: Funções puras são mais fáceis de testar
- ✅ **Biblioteca mais leve**: Menos código interno
- ✅ **Uso flexível**: Use apenas o que precisa

## 🚨 Tratamento de Erros

A biblioteca fornece classes de erro customizadas:

```typescript
import {
  InvalidCredentialsError,
  ValidationError,
  ApiClientError,
} from 'zdata-client';

try {
  const auth = await login(baseUrl, workspaceId, credentials);
} catch (error) {
  if (error instanceof InvalidCredentialsError) {
    console.error('Credenciais inválidas');
  } else if (error instanceof ApiClientError) {
    console.error(`Erro da API (${error.statusCode}):`, error.message);
  }
}
```

## 🔧 Desenvolvimento

```bash
# Instalar dependências
npm install

# Executar testes
npm test

# Build
npm run build

# Lint
npm run lint

# Type check
npm run type-check
```

## 📄 Licença

MIT

---

**ZData Client v2.0** - Uma biblioteca client de API TypeScript simples e poderosa. 🚀