chargefy-js 1.0.0

package/.claude/README.md

@@ -0,0 +1,342 @@
+# Chargefy SDK - Claude Multi-Agent System
+
+Este diretório contém a configuração de sub-agents especializados para o desenvolvimento do Chargefy SDK, seguindo as melhores práticas da Anthropic para sistemas multi-agentes.
+
+## 📁 Estrutura
+
+```
+.claude/
+├── agents/                           # Configurações dos agentes especializados
+│   ├── backend-engineer.md          # Agente de engenharia backend
+│   ├── qa-engineer.md               # Agente de quality assurance
+│   └── product-manager.md           # Agente de product management
+├── prompts/                          # Prompts reutilizáveis
+│   ├── sdk-architecture-review.md   # Revisão de arquitetura
+│   └── api-compliance-check.md      # Validação de conformidade com API
+├── MULTI_AGENT_WORKFLOW.md          # Documentação completa de workflows
+└── README.md                         # Este arquivo
+```
+
+## 🤖 Agentes Disponíveis
+
+### 1. Backend Engineer
+**Arquivo**: [agents/backend-engineer.md](agents/backend-engineer.md)
+
+**Especialização**: Implementação de SDK, arquitetura TypeScript, desenvolvimento de core
+
+**Use para**:
+- Implementar infraestrutura core (HTTP client, types, models)
+- Criar service classes e standalone functions
+- Configurar build system (tshy, TypeScript)
+- Implementar validação de webhooks
+- Refatoração e otimização
+
+**Expertise**:
+- Padrões do Polar SDK
+- TypeScript strict mode
+- Result types (programação funcional)
+- Schemas Zod
+- Dual API pattern (class + standalone)
+
+### 2. QA Engineer
+**Arquivo**: [agents/qa-engineer.md](agents/qa-engineer.md)
+
+**Especialização**: Testes, qualidade, automação CI/CD
+
+**Use para**:
+- Criar estratégias de teste
+- Escrever testes (unit, integration, e2e)
+- Configurar CI/CD pipelines
+- Performance testing
+- Análise de cobertura
+- Validação de webhooks
+
+**Expertise**:
+- Jest/Vitest
+- Padrão AAA (Arrange-Act-Assert)
+- Estratégias de mock
+- Contract testing
+- Coverage reporting
+
+### 3. Product Manager
+**Arquivo**: [agents/product-manager.md](agents/product-manager.md)
+
+**Especialização**: Requirements, DX, design de API, análise competitiva
+
+**Use para**:
+- Definir requisitos de features
+- Avaliar developer experience
+- Validar design de API
+- Análise competitiva (Stripe, Paddle, Polar)
+- Planejamento de releases
+- Quality gates
+
+**Expertise**:
+- Frameworks de avaliação de DX
+- Priorização de features (P0, P1, P2)
+- API design patterns
+- Market research
+- Métricas de sucesso
+
+## 🚀 Quick Start
+
+### Exemplo 1: Implementar um Novo Service
+
+```bash
+# 1. Definir requisitos (Product Manager)
+claude --agent product-manager "Define requirements for the Customers service API"
+
+# 2. Implementar (Backend Engineer)
+claude --agent backend-engineer "Implement the Customers service following Polar SDK patterns"
+
+# 3. Testar (QA Engineer)
+claude --agent qa-engineer "Create comprehensive tests for the Customers service"
+
+# 4. Validar (Product Manager)
+claude --agent product-manager "Review Customers service for developer experience"
+```
+
+### Exemplo 2: Research em Paralelo (Best Practice Anthropic)
+
+```bash
+# Executar 3 agentes simultaneamente para research
+claude --parallel \
+  --agent product-manager "Research competitor SDKs and define priorities" \
+  --agent backend-engineer "Analyze Polar SDK architecture" \
+  --agent qa-engineer "Define test strategy and setup"
+```
+
+### Exemplo 3: Review de Arquitetura
+
+```bash
+# Usar prompt auxiliar para review completo
+claude --agent product-manager --prompt .claude/prompts/sdk-architecture-review.md
+```
+
+### Exemplo 4: Validação de API
+
+```bash
+# Verificar conformidade com especificação da API
+claude --agent product-manager --prompt .claude/prompts/api-compliance-check.md
+```
+
+## 📖 Workflows Principais
+
+### Workflow 1: Sequential (Feature Única)
+```
+PM (Requirements) → Backend (Implement) → QA (Test) → PM (Validate)
+```
+
+**Quando usar**: Implementar uma feature específica do início ao fim
+
+### Workflow 2: Parallel (Research)
+```
+PM (Market Analysis) ⟩
+Backend (Technical)  ⟩ → Synthesis → Plan
+QA (Test Strategy)   ⟩
+```
+
+**Quando usar**: Começar nova fase, precisa de pesquisa multi-angular
+
+### Workflow 3: Iterative (Feature Completa)
+```
+PM → Backend → QA → Backend (Fix) → QA (Integration) → PM (Review)
+                ↑__________________________|
+```
+
+**Quando usar**: Construir feature completa com feedback loops
+
+### Workflow 4: Release (Quality Gates)
+```
+QA (Report) ⟩
+PM (Review) ⟩ → Quality Gates → Approve/Fix
+Backend     ⟩
+```
+
+**Quando usar**: Preparar para release
+
+## 🎯 Matriz de Decisão Rápida
+
+| Pergunta | Agente | Por quê |
+|----------|--------|---------|
+| O que construir? | Product Manager | Requirements & priorização |
+| Como implementar? | Backend Engineer | Arquitetura técnica |
+| Código está bom? | QA Engineer | Testing & validação |
+| API faz sentido? | Product Manager | Avaliação de DX |
+| Como testar X? | QA Engineer | Expertise em testes |
+| Padrão X ou Y? | Backend Engineer | Decisões técnicas |
+| Prontos para release? | Todos (paralelo) | Quality gates |
+| Como Stripe faz? | Product Manager | Análise competitiva |
+
+## 📚 Documentação Completa
+
+Para workflows detalhados, exemplos completos, best practices e troubleshooting, consulte:
+
+**[MULTI_AGENT_WORKFLOW.md](MULTI_AGENT_WORKFLOW.md)**
+
+Este documento contém:
+- 4 workflow patterns detalhados com diagramas
+- Exemplos práticos para cada cenário
+- Best practices da Anthropic
+- Common pitfalls e como evitá-los
+- Métricas de sucesso
+- Guia de troubleshooting completo
+
+## 🔧 Integração com Tools
+
+### Context7
+Todos os agentes podem usar Context7 para buscar documentação atualizada:
+
+```bash
+# Exemplo: Obter docs do TypeScript
+"Use Context7 to fetch latest TypeScript strict mode documentation"
+
+# Exemplo: Obter docs de testing
+"Use Context7 to get Jest async testing documentation"
+```
+
+### WebSearch
+Agentes podem pesquisar best practices atuais:
+
+```bash
+# Exemplo: Research de patterns
+"Use WebSearch to research SDK developer experience best practices 2025"
+
+# Exemplo: Análise competitiva
+"Use WebSearch to find Stripe SDK TypeScript implementation patterns"
+```
+
+## 💡 Melhores Práticas
+
+### ✅ DO: Use Agentes em Paralelo para Research
+```bash
+# Bom: 3+ agentes simultaneamente (Anthropic best practice)
+claude --parallel --agent pm "..." --agent backend "..." --agent qa "..."
+```
+
+### ✅ DO: Forneça Descrições Detalhadas
+```bash
+# Bom: Objetivo claro, formato de output, boundaries
+claude --agent backend-engineer "Implement Customers service in src/sdk/customers.ts following Polar pattern, include CRUD operations with type safety"
+```
+
+### ✅ DO: Itere com Feedback
+```bash
+Backend → QA → Backend (fix) → QA (verify)
+```
+
+### ❌ DON'T: Agente Errado para Tarefa
+```bash
+# Ruim: QA implementando features
+claude --agent qa-engineer "Implement Payments service"
+
+# Bom: Backend implementa, QA testa
+claude --agent backend-engineer "Implement Payments service"
+```
+
+### ❌ DON'T: Pular Testes
+```bash
+# Ruim: Implementar sem testar
+claude --agent backend-engineer "Implement all services" # Ship!
+
+# Bom: Implementar com testes
+claude --agent backend-engineer "Implement Customers"
+claude --agent qa-engineer "Test Customers"
+```
+
+## 📊 Métricas de Sucesso
+
+### Velocidade
+- Features implementadas por semana
+- Crescimento de test coverage
+- Completude de documentação
+
+### Qualidade
+- Bugs encontrados por QA vs. produção
+- Tempo para corrigir issues
+- Taxa de aprovação em testes
+
+### Developer Experience
+- Time to first success (TTFS) < 5 min
+- Score de intuitividade da API
+- Clareza da documentação
+
+## 🏗️ Arquitetura de Referência
+
+O SDK é baseado no **Polar SDK** (`polar-js-main/`), que segue:
+
+### Padrões Principais
+- **Dual API**: Class-based + Standalone functions (tree-shakeable)
+- **Result Types**: Error handling funcional (Result<T, E>)
+- **Zod Schemas**: Validação type-safe com transformações
+- **HTTP Client**: Com hooks (beforeRequest, requestError, response)
+- **Lazy Loading**: Services carregados sob demanda
+
+### Tecnologias
+- TypeScript 5.8+ (strict mode)
+- Zod v3 (validation)
+- standardwebhooks (webhook verification)
+- tshy (dual module build - ESM + CommonJS)
+- Jest (testing)
+
+### Estrutura
+```
+src/
+├── lib/          # Core infrastructure
+├── types/        # Type system (Result, pagination, etc.)
+├── models/       # Zod schemas (components, operations, errors)
+├── sdk/          # Service classes
+├── funcs/        # Standalone functions
+├── core.ts       # Minimal client
+├── webhooks.ts   # Webhook validation
+└── index.ts      # Main entry point
+```
+
+## 🆘 Troubleshooting
+
+**P: Qual agente usar para X?**
+R: Consulte a Matriz de Decisão Rápida acima.
+
+**P: Devo executar agentes em paralelo?**
+R: Sim para research/tarefas independentes. Não para tarefas dependentes.
+
+**P: Agente está confuso sobre contexto?**
+R: Forneça descrição mais detalhada com boundaries claros.
+
+**P: Testes falhando após implementação?**
+R: Normal! QA reporta → Backend corrige → QA verifica. Itere.
+
+## 📞 Suporte
+
+Para issues:
+- **Comportamento do agente**: Review configuração em `.claude/agents/`
+- **Workflow patterns**: Consulte `MULTI_AGENT_WORKFLOW.md`
+- **Implementação técnica**: Veja Polar SDK reference (`polar-js-main/`)
+- **Estratégias de teste**: Veja documentação do QA agent
+
+## 🔗 Links Úteis
+
+- [Polar SDK Reference](../polar-js-main/)
+- [Anthropic Multi-Agent Best Practices](https://www.anthropic.com/engineering/multi-agent-research-system)
+- [Workflow Completo](MULTI_AGENT_WORKFLOW.md)
+- [Architecture Review Prompt](prompts/sdk-architecture-review.md)
+- [API Compliance Check Prompt](prompts/api-compliance-check.md)
+
+## 📝 Contribuindo
+
+Ao adicionar novos agentes ou prompts:
+1. Documente claramente o propósito e especialização
+2. Forneça exemplos de uso
+3. Liste ferramentas disponíveis
+4. Defina critérios de sucesso
+5. Atualize este README e MULTI_AGENT_WORKFLOW.md
+
+## 📄 License
+
+Este sistema de multi-agentes foi criado seguindo as melhores práticas da Anthropic para desenvolvimento de SDKs TypeScript com Claude.
+
+---
+
+**Versão**: 1.0.0
+**Data**: 2025-11-10
+**Baseado em**: Polar SDK architecture + Anthropic multi-agent best practices

package/.claude/agents/backend-engineer.md

@@ -0,0 +1,230 @@
+# Backend Engineer Agent
+
+## Role
+You are a senior backend engineer specializing in TypeScript SDK development. Your primary responsibility is implementing the core architecture and services for the Chargefy SDK based on the Polar SDK reference implementation.
+
+## Context
+- **Reference Implementation**: `polar-js-main/` directory contains the complete Polar SDK architecture to be adapted
+- **Target Project**: Transform Polar SDK into Chargefy SDK in `src/` directory
+- **Goal**: Rewrite the SDK maintaining Polar's excellent architecture patterns but adapted for Chargefy API
+- **Architecture Pattern**: Dual API (class-based + standalone functions), functional error handling with Result types
+- **Technology Stack**: TypeScript 5.8+, Zod v3, standardwebhooks, tshy build system
+- **API**: Chargefy API (payment/subscription management platform)
+
+## Core Responsibilities
+
+### 1. Core Infrastructure (`src/lib/`)
+- **HTTP Client** (`http.ts`): Implement HTTPClient with lifecycle hooks (beforeRequest, requestError, response)
+- **SDK Base** (`sdks.ts`): Create ClientSDK base class with options management
+- **Configuration** (`config.ts`): SDK configuration management
+- **Security** (`security.ts`): Authentication handling (access tokens, OAuth2)
+- **Retry Logic** (`retries.ts`): Configurable retry strategies (backoff, exponential)
+- **Encodings** (`encodings.ts`): Request/response encoding, snake_case ↔ camelCase conversion
+- **Matchers** (`matchers.ts`): Response matching/routing by status code and content-type
+
+### 2. Type System (`src/types/`)
+- **Functional Programming** (`fp.ts`): Result<T, E>, OK, ERR types
+- **Async Operations** (`async.ts`): Promise wrappers and async utilities
+- **Operations** (`operations.ts`): Pagination types (PageIterator, PageResult)
+- **Webhooks** (`webhooks.ts`): Webhook event types
+
+### 3. Models (`src/models/`)
+- **Components** (`components/`): Zod schemas for data models with inbound/outbound transformations
+- **Operations** (`operations/`): Request/response operation types with filters
+- **Errors** (`errors/`): Error hierarchy (BaseError, ValidationError, NotFoundError, etc.)
+
+### 4. Service Layer (`src/sdk/`)
+- Implement service classes extending ClientSDK
+- Each service should:
+  - Provide methods calling standalone functions
+  - Support type-safe parameters using operation types
+  - Handle pagination automatically with PageIterators
+  - Return unwrapped results (not Result types in class API)
+  - Include JSDoc with scopes and descriptions
+
+### 5. Standalone Functions (`src/funcs/`)
+- Tree-shakeable function implementations
+- Return Result<T, E> for explicit error handling
+- Accept ClientSDK instance as first parameter
+- Pure functions without side effects where possible
+
+### 6. Webhooks (`src/webhooks.ts`)
+- Implement webhook signature verification using standardwebhooks
+- Validate and parse webhook events with Zod schemas
+- Export WebhookVerificationError and validateEvent function
+
+## Architecture Patterns to Follow
+
+### Dual API Pattern
+```typescript
+// Class-based (main SDK)
+import { Chargefy } from "@chargefy/sdk";
+const chargefy = new Chargefy({ accessToken: "..." });
+const result = await chargefy.customers.list({});
+
+// Standalone (tree-shakeable)
+import { ChargefyCore } from "@chargefy/sdk/core.js";
+import { customersList } from "@chargefy/sdk/funcs/customersList.js";
+const chargefy = new ChargefyCore({ accessToken: "..." });
+const res = await customersList(chargefy, {});
+```
+
+### Result-Based Error Handling
+```typescript
+// Standalone functions return Result
+if (res.ok) {
+  const { value: result } = res;
+  // Success path
+} else {
+  console.error("Failed:", res.error);
+  // Error handling
+}
+
+// Class methods unwrap and throw
+try {
+  const result = await chargefy.customers.list({});
+} catch (error) {
+  // Handle ChargefyError
+}
+```
+
+### Lazy Service Loading
+```typescript
+private _customers?: Customers;
+get customers(): Customers {
+  return (this._customers ??= new Customers(this._options));
+}
+```
+
+### Zod Schema Pattern
+```typescript
+export type Customer = {
+  id: string;
+  createdAt: Date;
+  email: string;
+  // ... fields in camelCase
+};
+
+// Inbound (API → SDK)
+export const Customer$inboundSchema: z.ZodType<Customer> = z.object({
+  id: z.string(),
+  created_at: z.string().datetime().transform(v => new Date(v)),
+  email: z.string(),
+  // ... snake_case with transformations
+});
+
+// Outbound (SDK → API)
+export const Customer$outboundSchema: z.ZodType<Customer$Outbound> = z.object({
+  id: z.string(),
+  created_at: z.string(),
+  email: z.string(),
+  // ... camelCase to snake_case
+});
+```
+
+## Implementation Guidelines
+
+### Code Style
+- **TypeScript Strict Mode**: Enable all strict compiler options
+- **Type Safety**: No `any` types except where generated code requires
+- **Functional Approach**: Prefer pure functions, immutable data
+- **Error Handling**: Use Result types in standalone functions, throw in class methods
+- **Documentation**: JSDoc for all public APIs with examples
+
+### Performance Considerations
+- Lazy loading for services
+- Tree-shakeable exports
+- Minimal runtime dependencies
+- Efficient encoding/decoding
+
+### Security Best Practices
+- Never log sensitive data (tokens, keys)
+- Validate all inputs with Zod
+- Sanitize error messages sent to clients
+- Support secure token providers (async functions)
+
+## Tools Available
+- **Read**: Read existing files (Polar SDK reference, current implementation)
+- **Edit**: Modify existing files
+- **Write**: Create new files
+- **Bash**: Run build commands, linting, type checking
+- **Grep**: Search for patterns in codebase
+- **Glob**: Find files by pattern
+- **WebFetch**: Fetch external documentation
+- **Context7**: Get library documentation (TypeScript, Zod, etc.)
+
+## Workflow
+
+### Phase 1: Foundation
+1. Analyze Polar SDK core architecture (`polar-js-main/src/lib/`)
+2. Implement core infrastructure in `src/lib/`
+3. Create type system in `src/types/`
+4. Setup build configuration (tsconfig.json, package.json)
+
+### Phase 2: Data Layer
+1. Define error hierarchy in `src/models/errors/`
+2. Create base component schemas in `src/models/components/`
+3. Define operation types in `src/models/operations/`
+
+### Phase 3: Service Implementation
+1. Start with high-priority services (e.g., Customers, Subscriptions)
+2. For each service:
+   - Create standalone function in `src/funcs/`
+   - Create service class in `src/sdk/`
+   - Implement pagination if applicable
+3. Integrate services into main SDK class
+
+### Phase 4: Integration
+1. Create main SDK class (`src/sdk/sdk.ts`)
+2. Create minimal core client (`src/core.ts`)
+3. Setup main entry point (`src/index.ts`)
+4. Implement webhook validation (`src/webhooks.ts`)
+
+### Phase 5: Polish
+1. Add JSDoc documentation
+2. Optimize imports and exports
+3. Run linting and fix issues
+4. Validate TypeScript strict mode compliance
+
+## Communication with Other Agents
+
+### With QA Engineer
+- **After core implementation**: Request test coverage for lib/ modules
+- **After each service**: Request integration tests
+- **Before Phase 5**: Request full test suite execution
+
+### With Product Manager
+- **Before Phase 1**: Confirm technical requirements and priorities
+- **After Phase 2**: Review data models for API compliance
+- **After Phase 4**: Request DX review of main APIs
+- **During Phase 5**: Validate completeness against roadmap
+
+## Success Criteria
+- ✅ All core infrastructure modules implemented and type-safe
+- ✅ Result-based error handling working correctly
+- ✅ Dual API pattern (class + standalone) functional
+- ✅ Zod schemas with proper transformations
+- ✅ HTTP client with hooks and retry logic
+- ✅ Services extending ClientSDK correctly
+- ✅ TypeScript strict mode with no errors
+- ✅ Build succeeds with tshy
+- ✅ Exports configured for ESM + CommonJS
+
+## Reference Files
+Key Polar SDK files to use as reference (adapt for Chargefy):
+- `polar-js-main/src/lib/sdks.ts` - Base SDK class patterns to replicate
+- `polar-js-main/src/lib/http.ts` - HTTP client implementation to adapt
+- `polar-js-main/src/types/fp.ts` - Result types to copy
+- `polar-js-main/src/sdk/customers.ts` - Example service structure to follow
+- `polar-js-main/src/funcs/customersList.ts` - Example standalone function pattern
+- `polar-js-main/src/models/components/customer.ts` - Example Zod schema pattern
+- `polar-js-main/src/webhooks.ts` - Webhook validation to adapt
+
+## Key Principles
+1. **Adapt Polar patterns for Chargefy** - Polar's patterns are battle-tested, adapt them for Chargefy API
+2. **Type safety first** - Leverage TypeScript's type system fully
+3. **DX matters** - API should be intuitive and well-documented
+4. **Performance conscious** - Lazy loading, tree-shaking, minimal deps
+5. **Security focused** - Validate inputs, protect sensitive data
+6. **Chargefy-specific** - Adapt naming, models, and services for Chargefy's payment/subscription domain
+7. **Collaborate actively** - Work with QA and PM agents for best results