chargefy-js 1.0.0

package/.claude/EXAMPLE_SESSION.md

@@ -0,0 +1,647 @@
+# Example Session: Implementing Customers Service
+
+Este documento mostra um exemplo prático completo de como usar os sub-agents para implementar o serviço de Customers do zero.
+
+## 📋 Cenário
+
+**Objetivo**: Implementar o serviço de Customers com operações CRUD completas
+**Duração estimada**: 2-3 horas
+**Agentes envolvidos**: Product Manager, Backend Engineer, QA Engineer
+
+---
+
+## Phase 1: Requirements Definition (Product Manager)
+
+### Comando:
+```bash
+claude --agent product-manager "Define complete requirements for the Customers service API including create, list, get, update, delete, and search operations. Include acceptance criteria and success metrics."
+```
+
+### Resposta Esperada:
+O Product Manager deve retornar:
+- User stories detalhadas
+- Acceptance criteria para cada operação
+- Data model (campos do Customer)
+- Success metrics (TTFS, error rate)
+- Priorização (P0, P1, P2)
+
+### Exemplo de Output:
+```markdown
+# Customers Service Requirements
+
+## Priority: P0 (Must-Have for MVP)
+
+## User Stories
+
+### 1. Create Customer
+**As a** developer
+**I want to** create a new customer with email and metadata
+**So that** I can track my users in the payment system
+
+**Acceptance Criteria**:
+- [ ] Email is required and validated
+- [ ] Name is optional
+- [ ] Metadata (key-value) supported
+- [ ] Returns created customer with ID
+- [ ] Validates duplicate emails
+- [ ] Type-safe TypeScript API
+
+### 2. List Customers
+... (continues)
+
+## Data Model
+```typescript
+interface Customer {
+  id: string;
+  createdAt: Date;
+  updatedAt: Date;
+  email: string;
+  name: string | null;
+  metadata: Record<string, any>;
+  organizationId: string;
+}
+```
+
+## API Design
+- POST /customers - Create
+- GET /customers - List (with pagination)
+- GET /customers/:id - Get by ID
+- PATCH /customers/:id - Update
+- DELETE /customers/:id - Delete
+```
+
+---
+
+## Phase 2: Implementation (Backend Engineer)
+
+### Comando 1: Analyze Reference
+```bash
+claude --agent backend-engineer "Analyze the Customers service implementation in polar-js-main/src/sdk/customers.ts and polar-js-main/src/funcs/customersList.ts to understand the patterns we should follow"
+```
+
+### Comando 2: Implement Data Model
+```bash
+claude --agent backend-engineer "Implement Customer Zod schema in src/models/components/customer.ts with inbound and outbound transformations following the pattern from polar-js-main/src/models/components/customer.ts"
+```
+
+### Resposta Esperada:
+```typescript
+// src/models/components/customer.ts
+import { z } from 'zod';
+
+export type Customer = {
+  id: string;
+  createdAt: Date;
+  updatedAt: Date;
+  email: string;
+  name: string | null;
+  metadata: Record<string, any> | null;
+  organizationId: string;
+};
+
+// Inbound schema (API → SDK)
+export const Customer$inboundSchema: z.ZodType<Customer, z.ZodTypeDef, any> =
+  z.object({
+    id: z.string(),
+    created_at: z.string().datetime().transform(v => new Date(v)),
+    updated_at: z.string().datetime().transform(v => new Date(v)),
+    email: z.string().email(),
+    name: z.string().nullable(),
+    metadata: z.record(z.any()).nullable(),
+    organization_id: z.string(),
+  }).transform(input => ({
+    id: input.id,
+    createdAt: input.created_at,
+    updatedAt: input.updated_at,
+    email: input.email,
+    name: input.name,
+    metadata: input.metadata,
+    organizationId: input.organization_id,
+  }));
+
+// Outbound schema (SDK → API)
+export type Customer$Outbound = {
+  id: string;
+  created_at: string;
+  updated_at: string;
+  email: string;
+  name: string | null;
+  metadata: Record<string, any> | null;
+  organization_id: string;
+};
+
+export const Customer$outboundSchema: z.ZodType<Customer$Outbound, z.ZodTypeDef, Customer> =
+  z.object({
+    id: z.string(),
+    createdAt: z.date().transform(v => v.toISOString()),
+    updatedAt: z.date().transform(v => v.toISOString()),
+    email: z.string().email(),
+    name: z.string().nullable(),
+    metadata: z.record(z.any()).nullable(),
+    organizationId: z.string(),
+  }).transform(input => ({
+    id: input.id,
+    created_at: input.createdAt,
+    updated_at: input.updatedAt,
+    email: input.email,
+    name: input.name,
+    metadata: input.metadata,
+    organization_id: input.organizationId,
+  }));
+```
+
+### Comando 3: Implement Standalone Functions
+```bash
+claude --agent backend-engineer "Implement standalone functions for Customers service in src/funcs/:
+- customersList (with pagination)
+- customersCreate
+- customersGet
+- customersUpdate
+- customersDelete
+
+Each function should return Result<T, E> and follow the pattern from polar-js-main/src/funcs/"
+```
+
+### Exemplo de Output:
+```typescript
+// src/funcs/customersList.ts
+import { ClientSDK } from '../lib/sdks.js';
+import { Result } from '../types/fp.js';
+import { Customer, Customer$inboundSchema } from '../models/components/customer.js';
+
+export interface CustomersListRequest {
+  organizationId?: string;
+  limit?: number;
+  page?: number;
+}
+
+export interface CustomersListResponse {
+  data: Customer[];
+  pagination: {
+    total: number;
+    page: number;
+    limit: number;
+  };
+}
+
+export async function customersList(
+  client: ClientSDK,
+  request: CustomersListRequest = {}
+): Promise<Result<CustomersListResponse, Error>> {
+  try {
+    const response = await client.httpClient.get('/customers', {
+      params: request
+    });
+
+    const data = response.data.map(item =>
+      Customer$inboundSchema.parse(item)
+    );
+
+    return {
+      ok: true,
+      value: {
+        data,
+        pagination: response.pagination
+      }
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error : new Error('Unknown error')
+    };
+  }
+}
+```
+
+### Comando 4: Implement Service Class
+```bash
+claude --agent backend-engineer "Implement Customers service class in src/sdk/customers.ts that extends ClientSDK and provides methods calling the standalone functions. Include JSDoc with scopes and examples."
+```
+
+### Exemplo de Output:
+```typescript
+// src/sdk/customers.ts
+import { ClientSDK } from '../lib/sdks.js';
+import * as funcs from '../funcs/customersList.js';
+import { Customer } from '../models/components/customer.js';
+
+/**
+ * Customers service for managing customer records
+ */
+export class Customers extends ClientSDK {
+  /**
+   * List all customers
+   *
+   * @example
+   * ```typescript
+   * const customers = await chargefy.customers.list({
+   *   organizationId: 'org-123',
+   *   limit: 50
+   * });
+   * ```
+   *
+   * Scopes: customers:read
+   */
+  async list(request: funcs.CustomersListRequest = {}): Promise<funcs.CustomersListResponse> {
+    const result = await funcs.customersList(this, request);
+    if (result.ok) {
+      return result.value;
+    }
+    throw result.error;
+  }
+
+  /**
+   * Create a new customer
+   *
+   * @example
+   * ```typescript
+   * const customer = await chargefy.customers.create({
+   *   email: 'user@example.com',
+   *   name: 'John Doe',
+   *   metadata: { plan: 'premium' }
+   * });
+   * ```
+   *
+   * Scopes: customers:write
+   */
+  async create(request: funcs.CustomersCreateRequest): Promise<Customer> {
+    const result = await funcs.customersCreate(this, request);
+    if (result.ok) {
+      return result.value;
+    }
+    throw result.error;
+  }
+
+  // ... get, update, delete methods
+}
+```
+
+### Comando 5: Integrate into Main SDK
+```bash
+claude --agent backend-engineer "Add Customers service to the main Chargefy SDK class in src/sdk/sdk.ts with lazy loading pattern"
+```
+
+---
+
+## Phase 3: Testing (QA Engineer)
+
+### Comando 1: Unit Tests for Schema
+```bash
+claude --agent qa-engineer "Create unit tests for Customer Zod schema in src/models/components/customer.test.ts testing valid data, invalid data, and transformations"
+```
+
+### Exemplo de Output:
+```typescript
+// src/models/components/customer.test.ts
+import { Customer$inboundSchema, Customer$outboundSchema } from './customer';
+
+describe('Customer Schema', () => {
+  describe('inbound schema', () => {
+    it('should validate valid customer data', () => {
+      const apiData = {
+        id: 'cus_123',
+        created_at: '2025-01-01T00:00:00Z',
+        updated_at: '2025-01-01T00:00:00Z',
+        email: 'test@example.com',
+        name: 'Test User',
+        metadata: { plan: 'premium' },
+        organization_id: 'org_123'
+      };
+
+      const result = Customer$inboundSchema.safeParse(apiData);
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.createdAt).toBeInstanceOf(Date);
+        expect(result.data.organizationId).toBe('org_123');
+      }
+    });
+
+    it('should reject invalid email', () => {
+      const invalidData = {
+        id: 'cus_123',
+        created_at: '2025-01-01T00:00:00Z',
+        updated_at: '2025-01-01T00:00:00Z',
+        email: 'not-an-email',
+        name: 'Test',
+        metadata: null,
+        organization_id: 'org_123'
+      };
+
+      const result = Customer$inboundSchema.safeParse(invalidData);
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('outbound schema', () => {
+    it('should transform SDK format to API format', () => {
+      const sdkData = {
+        id: 'cus_123',
+        createdAt: new Date('2025-01-01T00:00:00Z'),
+        updatedAt: new Date('2025-01-01T00:00:00Z'),
+        email: 'test@example.com',
+        name: 'Test User',
+        metadata: { plan: 'premium' },
+        organizationId: 'org_123'
+      };
+
+      const result = Customer$outboundSchema.parse(sdkData);
+
+      expect(result.created_at).toBe('2025-01-01T00:00:00.000Z');
+      expect(result.organization_id).toBe('org_123');
+    });
+  });
+});
+```
+
+### Comando 2: Unit Tests for Standalone Functions
+```bash
+claude --agent qa-engineer "Create unit tests for customersList standalone function in src/funcs/customersList.test.ts testing success case, pagination, and error handling"
+```
+
+### Comando 3: Integration Tests for Service
+```bash
+claude --agent qa-engineer "Create integration tests for Customers service in src/__tests__/integration/customers.test.ts testing all CRUD operations with mocked HTTP client"
+```
+
+### Exemplo de Output:
+```typescript
+// src/__tests__/integration/customers.test.ts
+import { Chargefy } from '../../sdk/sdk';
+
+describe('Customers Service Integration', () => {
+  let chargefy: Chargefy;
+
+  beforeEach(() => {
+    chargefy = new Chargefy({
+      accessToken: 'test-token',
+      serverURL: 'http://localhost:3000'
+    });
+  });
+
+  describe('list', () => {
+    it('should list customers with default pagination', async () => {
+      // Mock HTTP response
+      mockHttpClient.get.mockResolvedValue({
+        data: [
+          {
+            id: 'cus_1',
+            created_at: '2025-01-01T00:00:00Z',
+            updated_at: '2025-01-01T00:00:00Z',
+            email: 'user1@example.com',
+            name: 'User 1',
+            metadata: null,
+            organization_id: 'org_1'
+          }
+        ],
+        pagination: {
+          total: 1,
+          page: 1,
+          limit: 50
+        }
+      });
+
+      const result = await chargefy.customers.list();
+
+      expect(result.data).toHaveLength(1);
+      expect(result.data[0].email).toBe('user1@example.com');
+      expect(result.pagination.total).toBe(1);
+    });
+
+    it('should handle empty results', async () => {
+      mockHttpClient.get.mockResolvedValue({
+        data: [],
+        pagination: { total: 0, page: 1, limit: 50 }
+      });
+
+      const result = await chargefy.customers.list();
+      expect(result.data).toHaveLength(0);
+    });
+  });
+
+  describe('create', () => {
+    it('should create customer with valid data', async () => {
+      const newCustomer = {
+        email: 'new@example.com',
+        name: 'New User'
+      };
+
+      mockHttpClient.post.mockResolvedValue({
+        id: 'cus_new',
+        created_at: '2025-01-01T00:00:00Z',
+        updated_at: '2025-01-01T00:00:00Z',
+        email: newCustomer.email,
+        name: newCustomer.name,
+        metadata: null,
+        organization_id: 'org_1'
+      });
+
+      const customer = await chargefy.customers.create(newCustomer);
+
+      expect(customer.id).toBe('cus_new');
+      expect(customer.email).toBe(newCustomer.email);
+    });
+
+    it('should throw ValidationError for invalid email', async () => {
+      mockHttpClient.post.mockRejectedValue(
+        new ValidationError('Invalid email format')
+      );
+
+      await expect(
+        chargefy.customers.create({ email: 'invalid' })
+      ).rejects.toThrow(ValidationError);
+    });
+  });
+});
+```
+
+### Comando 4: Run Tests
+```bash
+claude --agent qa-engineer "Run all tests for Customers service and report coverage"
+```
+
+---
+
+## Phase 4: DX Review (Product Manager)
+
+### Comando:
+```bash
+claude --agent product-manager "Review the Customers service implementation for developer experience. Check:
+1. API intuitiveness
+2. TypeScript autocomplete
+3. Error messages
+4. Example code quality
+5. Time to first success
+
+Use the implementation in src/sdk/customers.ts and tests as reference."
+```
+
+### Resposta Esperada:
+```markdown
+# Customers Service DX Review
+
+## Summary
+Overall excellent DX. Found 1 minor issue, 2 improvements suggested.
+
+## ✅ Strengths
+
+### 1. API Intuitiveness (9/10)
+- Method names are clear and predictable
+- Parameters follow intuitive patterns
+- Consistent with industry standards (Stripe, Polar)
+
+```typescript
+// Very intuitive - developers can guess this
+await chargefy.customers.create({ email: '...' })
+await chargefy.customers.list({ limit: 50 })
+```
+
+### 2. TypeScript Support (10/10)
+- Autocomplete works perfectly
+- All types exported
+- Excellent type inference
+- No need to manually type responses
+
+### 3. Error Messages (8/10)
+- ValidationError includes field information
+- Clear error types
+- Missing: More specific error codes (see improvements)
+
+### 4. Time to First Success
+- Estimated: 3 minutes ✅ (Target: < 5 min)
+- Steps: Install → Import → Configure → Create customer
+
+## 💡 Improvements Suggested
+
+1. **Add example for pagination**
+   Current examples don't show pagination pattern
+
+2. **More specific error codes**
+   Add error codes like 'duplicate_email', 'invalid_format'
+
+## ⚠️ Issues Found
+
+1. **Minor**: Missing JSDoc for some optional parameters
+
+## Recommendation
+✅ **APPROVED for MVP** - Issues are minor and can be addressed in patches
+```
+
+---
+
+## Phase 5: Iteration (If Needed)
+
+Se o PM identificou issues, voltamos ao Backend Engineer:
+
+### Comando:
+```bash
+claude --agent backend-engineer "Address DX issues found in review:
+1. Add pagination example to JSDoc
+2. Enhance error messages with specific codes
+3. Add missing JSDoc for optional parameters"
+```
+
+Depois QA valida:
+
+### Comando:
+```bash
+claude --agent qa-engineer "Run regression tests to verify DX improvements don't break existing functionality"
+```
+
+---
+
+## Phase 6: Documentation & Finalization
+
+### Comando Final:
+```bash
+claude --agent product-manager "Create a summary of the Customers service implementation including:
+- Features delivered
+- Test coverage achieved
+- DX score
+- Known limitations
+- Next steps"
+```
+
+---
+
+## 📊 Session Summary
+
+### Time Breakdown
+- **Phase 1 (Requirements)**: 15 min
+- **Phase 2 (Implementation)**: 60-90 min
+- **Phase 3 (Testing)**: 45-60 min
+- **Phase 4 (Review)**: 15 min
+- **Phase 5 (Iteration)**: 20 min (if needed)
+- **Phase 6 (Documentation)**: 10 min
+
+**Total**: ~2.5-3 hours
+
+### Deliverables Created
+- ✅ Customer data model with Zod schemas
+- ✅ 5 standalone functions (list, create, get, update, delete)
+- ✅ Customers service class
+- ✅ Integration with main SDK
+- ✅ Comprehensive test suite (unit + integration)
+- ✅ Documentation and examples
+
+### Metrics Achieved
+- **Test Coverage**: 85%
+- **DX Score**: 9/10
+- **TTFS**: 3 minutes
+- **Type Safety**: 100%
+
+### Success Factors
+1. ✅ Clear requirements from PM upfront
+2. ✅ Following Polar SDK patterns (Backend)
+3. ✅ Comprehensive testing (QA)
+4. ✅ DX validation before finalization (PM)
+5. ✅ Quick iteration on feedback
+
+---
+
+## 💡 Lessons Learned
+
+### What Worked Well
+- **Parallel research** at the start saved time
+- **Detailed requirements** prevented rework
+- **Following reference patterns** (Polar SDK) ensured quality
+- **Testing as we go** caught issues early
+- **DX review** identified improvements before release
+
+### What Could Be Better
+- Could have run Backend + QA in parallel for some tasks
+- Could have created mock data fixtures earlier
+
+### Anthropic Best Practices Applied
+✅ Detailed task descriptions for each agent
+✅ Clear boundaries and responsibilities
+✅ Iterative feedback loops
+✅ Context isolation per agent
+✅ Scale effort to complexity (5 agents total, appropriate for feature)
+
+---
+
+## 🔄 Next Steps
+
+```bash
+# Apply same pattern to next service
+claude --agent product-manager "Define requirements for Subscriptions service following same template as Customers"
+
+# Or move to integration
+claude --agent backend-engineer "Integrate Customers service with authentication and error handling"
+
+# Or improve documentation
+claude --agent product-manager "Create getting started guide using Customers as example"
+```
+
+---
+
+## 📝 Notes
+
+- This example shows a **complete feature implementation** from requirements to testing
+- Real sessions may have more back-and-forth
+- Iteration is normal and expected
+- Each agent brings specialized expertise
+- The workflow is flexible - adapt to your needs
+
+**Tip**: Use this as a template for implementing other services!