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

npm install zdata-client

🔑 Autenticação

Login

import { login } from 'zdata-client';

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

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

Registro

import { register } from 'zdata-client';

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

console.log(authResponse.access_token);

🗄️ Operações CRUD

Usando ResourceRepository

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: '[email protected]'
});

// 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

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:

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: "[email protected]",
//   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

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)

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: '[email protected]',
  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:

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:

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):

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

await client.login({ email: '[email protected]', password: 'pass' });
const users = await client.findRecords({ resourceName: 'users' });

Agora (v2.0):

// 1. Login separado
const auth = await login('https://api.example.com', 'workspace-id', {
  email: '[email protected]', 
  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:

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

# 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. 🚀