chargefy-js 1.0.0

package/.claude/prompts/api-compliance-check.md

@@ -0,0 +1,372 @@
+# API Compliance Check Prompt
+
+Use this prompt to validate that the SDK implementation matches the Chargefy API specification and follows API design best practices.
+
+## Compliance Areas
+
+### 1. Endpoint Coverage
+- [ ] All documented API endpoints have SDK methods
+- [ ] Endpoint paths match API specification
+- [ ] HTTP methods (GET, POST, PUT, DELETE, PATCH) are correct
+- [ ] Query parameters are supported
+- [ ] Path parameters are supported
+- [ ] Request body schemas match specification
+
+### 2. Request Format
+- [ ] Content-Type headers are correct (application/json)
+- [ ] Request bodies are properly encoded
+- [ ] Query parameters are URL-encoded
+- [ ] Path parameters are properly substituted
+- [ ] Special characters are handled correctly
+- [ ] Arrays/objects in query params follow convention
+
+### 3. Response Handling
+- [ ] Success responses (2xx) are parsed correctly
+- [ ] Error responses (4xx, 5xx) are handled
+- [ ] Response schemas match specification
+- [ ] Status codes are interpreted correctly
+- [ ] Headers are accessible (pagination, rate limits)
+- [ ] Empty responses (204) are handled
+
+### 4. Authentication
+- [ ] API key authentication works
+- [ ] OAuth2 flows supported (if applicable)
+- [ ] Bearer token format is correct
+- [ ] Authentication errors are clear (401, 403)
+- [ ] Token refresh works (if applicable)
+
+### 5. Pagination
+- [ ] Cursor-based pagination works
+- [ ] Page-based pagination works (if applicable)
+- [ ] Limit/offset parameters respected
+- [ ] Next/previous page links parsed
+- [ ] Total count available (if provided by API)
+- [ ] Iteration works correctly
+
+### 6. Filtering & Sorting
+- [ ] Filter parameters match API spec
+- [ ] Operators (eq, gt, lt, etc.) work correctly
+- [ ] Multiple filters can be combined
+- [ ] Sort parameters work correctly
+- [ ] Sort direction (asc/desc) supported
+
+### 7. Webhooks
+- [ ] All webhook event types defined
+- [ ] Event schemas match API specification
+- [ ] Signature verification algorithm correct
+- [ ] Timestamp validation works
+- [ ] Replay attack protection implemented
+
+### 8. Error Codes
+- [ ] All error codes from API documented
+- [ ] Error response format matches API
+- [ ] Error messages are preserved
+- [ ] Validation errors include field details
+- [ ] Rate limit errors include retry-after
+
+### 9. Idempotency
+- [ ] Idempotency keys supported (if API requires)
+- [ ] Key generation is correct
+- [ ] Duplicate request handling tested
+
+### 10. Rate Limiting
+- [ ] Rate limit headers are read
+- [ ] Rate limit information exposed
+- [ ] Retry-After header respected
+- [ ] 429 responses handled gracefully
+
+## API Specification Checklist
+
+### Data Types
+- [ ] String fields validated (length, format)
+- [ ] Number fields validated (range, precision)
+- [ ] Boolean fields handled
+- [ ] Date/DateTime parsed correctly (ISO 8601)
+- [ ] Enum values validated
+- [ ] Arrays handled correctly
+- [ ] Nested objects supported
+- [ ] Null/undefined distinction preserved
+
+### Required vs Optional
+- [ ] Required fields enforced
+- [ ] Optional fields work when omitted
+- [ ] Default values applied correctly
+- [ ] Nullable fields handled
+
+### Field Naming
+- [ ] API uses snake_case
+- [ ] SDK uses camelCase
+- [ ] Transformation is bidirectional
+- [ ] No field names are lost
+- [ ] Special characters handled (e.g., $ in MongoDB)
+
+### API Versioning
+- [ ] API version in URL or header
+- [ ] Version is configurable
+- [ ] Breaking changes handled
+- [ ] Deprecation warnings shown
+
+## REST Best Practices
+
+### HTTP Methods
+- ✅ GET: Read, no side effects, idempotent
+- ✅ POST: Create, side effects, not idempotent
+- ✅ PUT: Update/replace, idempotent
+- ✅ PATCH: Partial update, may be idempotent
+- ✅ DELETE: Remove, idempotent
+
+### Status Codes
+- ✅ 200 OK: Success with body
+- ✅ 201 Created: Resource created
+- ✅ 204 No Content: Success without body
+- ✅ 400 Bad Request: Client error
+- ✅ 401 Unauthorized: Authentication failed
+- ✅ 403 Forbidden: Not authorized
+- ✅ 404 Not Found: Resource doesn't exist
+- ✅ 422 Unprocessable Entity: Validation failed
+- ✅ 429 Too Many Requests: Rate limited
+- ✅ 500 Internal Server Error: Server error
+- ✅ 503 Service Unavailable: Temporary issue
+
+### Resource Naming
+- ✅ Plural nouns for collections: `/customers`
+- ✅ IDs in path: `/customers/{id}`
+- ✅ Actions as nested resources: `/customers/{id}/activate`
+- ✅ Consistent naming across resources
+
+## Validation Process
+
+### 1. Documentation Review
+Compare SDK implementation with API documentation:
+```typescript
+// API Docs say: POST /customers
+// SDK should have:
+chargefy.customers.create({ email: "..." })
+
+// Verify:
+// - Method name matches operation
+// - Parameters match request body
+// - Response type matches API response
+```
+
+### 2. Schema Validation
+For each data model:
+```typescript
+// Check Zod schema matches API spec
+const CustomerSchema = z.object({
+  id: z.string(),
+  created_at: z.string().datetime(),
+  email: z.string().email(),
+  // ... all fields from API spec
+});
+
+// Validate both directions
+const inboundWorks = CustomerSchema.safeParse(apiResponse);
+const outboundWorks = CustomerOutboundSchema.safeParse(sdkData);
+```
+
+### 3. Example Testing
+Test with real API examples:
+```typescript
+// Use examples from API documentation
+const exampleFromDocs = {
+  "id": "cus_1234",
+  "created_at": "2025-01-01T00:00:00Z",
+  "email": "test@example.com"
+};
+
+// Should parse without errors
+const parsed = Customer$inboundSchema.parse(exampleFromDocs);
+```
+
+### 4. Error Case Testing
+Test error responses match API:
+```typescript
+// API returns 422 with validation errors
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Invalid email format",
+    "fields": {
+      "email": "Must be a valid email address"
+    }
+  }
+}
+
+// SDK should expose this structure
+try {
+  await chargefy.customers.create({ email: "invalid" });
+} catch (error) {
+  expect(error).toBeInstanceOf(ValidationError);
+  expect(error.fields.email).toBeDefined();
+}
+```
+
+## Compliance Red Flags
+
+### Critical
+- ❌ Missing required API endpoints
+- ❌ Incorrect HTTP methods
+- ❌ Wrong request/response formats
+- ❌ Authentication doesn't work
+- ❌ Data loss in transformations
+- ❌ Wrong API version
+
+### Major
+- ⚠️ Missing optional parameters
+- ⚠️ Incomplete error handling
+- ⚠️ Pagination issues
+- ⚠️ Webhook events missing
+- ⚠️ Rate limiting not handled
+
+### Minor
+- ℹ️ Inconsistent naming
+- ℹ️ Missing convenience methods
+- ℹ️ Suboptimal defaults
+- ℹ️ Documentation gaps
+
+## OpenAPI Integration
+
+If Chargefy provides an OpenAPI specification:
+
+### Validation Steps
+1. **Load OpenAPI Spec**
+   ```bash
+   # Validate spec is valid
+   npx @apidevtools/swagger-cli validate openapi.yaml
+   ```
+
+2. **Generate Types** (optional)
+   ```bash
+   # Generate types from spec
+   npx openapi-typescript openapi.yaml --output types.ts
+   ```
+
+3. **Compare Implementations**
+   ```typescript
+   // For each endpoint in OpenAPI:
+   // - Verify SDK has corresponding method
+   // - Compare parameter types
+   // - Compare response types
+   // - Check error responses
+   ```
+
+4. **Automated Testing**
+   ```bash
+   # Use tools like Dredd or Prism
+   npx @stoplight/prism-cli mock openapi.yaml
+   # Run SDK tests against mock server
+   ```
+
+## Compliance Report Template
+
+```markdown
+# API Compliance Report
+Date: 2025-11-10
+API Version: 1.0.0
+SDK Version: 0.1.0
+Reviewer: [Agent Name]
+
+## Summary
+Reviewed SDK compliance with Chargefy API specification. Found X compliant endpoints, Y issues.
+
+## Endpoint Coverage
+Total API endpoints: X
+Implemented in SDK: Y
+Coverage: Z%
+
+### Missing Endpoints
+- [ ] GET /endpoint1 - Priority: P1
+- [ ] POST /endpoint2 - Priority: P2
+
+### Incorrect Implementations
+- [ ] GET /customers - Wrong response type
+- [ ] POST /subscriptions - Missing parameter
+
+## Schema Compliance
+### Fully Compliant
+- ✅ Customer schema
+- ✅ Subscription schema
+
+### Issues Found
+- ❌ Payment schema: Missing `metadata` field
+- ⚠️ Refund schema: Optional field marked as required
+
+## Authentication
+- ✅ API key authentication works
+- ✅ Bearer token format correct
+- ⚠️ OAuth2 not implemented (P2)
+
+## Webhooks
+- ✅ Signature verification correct
+- ✅ All event types defined
+- ⚠️ Missing event: `subscription.paused`
+
+## Error Handling
+- ✅ Validation errors mapped correctly
+- ✅ Rate limit errors handled
+- ❌ 503 errors not retried automatically
+
+## Recommendations
+1. Implement missing endpoints (P1 items)
+2. Fix schema issues in Payment model
+3. Add missing webhook event types
+4. Implement automatic retry for 503
+
+## Compliance Score
+Overall: 87/100
+
+- Endpoint Coverage: 90/100
+- Schema Compliance: 85/100
+- Authentication: 90/100
+- Error Handling: 80/100
+
+## Conclusion
+**Status: Compliant with Exceptions**
+
+SDK is substantially compliant with API specification. Exceptions documented and acceptable for initial release. Recommend addressing high-priority issues before 1.0.
+```
+
+## Usage
+
+### Manual Review
+```bash
+# Review API compliance
+claude --agent product-manager --prompt .claude/prompts/api-compliance-check.md
+
+# Or with specific API version
+claude --agent product-manager \
+  --prompt .claude/prompts/api-compliance-check.md \
+  --context "API_VERSION=1.0.0"
+```
+
+### Automated Testing
+```typescript
+// In test file
+describe('API Compliance', () => {
+  it('should match OpenAPI spec', async () => {
+    const spec = loadOpenAPISpec();
+    const sdk = new Chargefy({ accessToken: 'test' });
+
+    // Validate all endpoints exist
+    for (const path of spec.paths) {
+      // Check SDK has method for this endpoint
+      expect(sdk).toHaveEndpoint(path);
+    }
+  });
+});
+```
+
+## API Documentation Resources
+Use these tools to research API best practices:
+- **WebSearch**: "REST API design best practices 2025"
+- **Context7**: Get documentation for HTTP libraries
+- **WebFetch**: Fetch competitor API documentation
+- **Read**: Review Chargefy API documentation (if available)
+
+## Tools for Validation
+- **OpenAPI Validator**: Validate spec files
+- **Prism**: Mock API server from OpenAPI
+- **Dredd**: API contract testing
+- **Postman**: Manual API testing
+- **Jest**: Automated compliance tests

package/.claude/prompts/sdk-architecture-review.md

@@ -0,0 +1,233 @@
+# SDK Architecture Review Prompt
+
+Use this prompt to conduct a comprehensive review of the SDK architecture, typically before major milestones or releases.
+
+## Review Areas
+
+### 1. Core Infrastructure
+- [ ] HTTP client implementation follows best practices
+- [ ] Retry logic handles all failure scenarios gracefully
+- [ ] Authentication mechanism is secure and flexible
+- [ ] Hooks system is properly documented and tested
+- [ ] Encoding/decoding transformations are bidirectional and lossless
+
+### 2. Type System
+- [ ] Result types provide clear success/error paths
+- [ ] Type inference works correctly throughout
+- [ ] Generic constraints are appropriate
+- [ ] No use of `any` except where absolutely necessary
+- [ ] Types are exported and accessible to consumers
+
+### 3. API Design
+- [ ] Naming is consistent across all services
+- [ ] Methods follow predictable patterns
+- [ ] Parameters are intuitive and well-documented
+- [ ] Return types are consistent
+- [ ] Dual API (class + standalone) works correctly
+
+### 4. Error Handling
+- [ ] Error hierarchy is logical and complete
+- [ ] Error messages are actionable
+- [ ] All error cases are covered
+- [ ] Network errors are properly wrapped
+- [ ] Validation errors include field information
+
+### 5. Data Models
+- [ ] Zod schemas validate all required fields
+- [ ] Optional/nullable fields handled correctly
+- [ ] Transformations preserve data integrity
+- [ ] Schema matches API specification
+- [ ] Breaking changes are documented
+
+### 6. Developer Experience
+- [ ] TypeScript autocomplete works perfectly
+- [ ] Examples are clear and runnable
+- [ ] Error messages guide developers to solutions
+- [ ] Getting started time < 5 minutes
+- [ ] Common use cases have examples
+
+### 7. Performance
+- [ ] Bundle size is optimized (tree-shaking works)
+- [ ] No memory leaks detected
+- [ ] HTTP requests are efficient
+- [ ] Encoding/decoding is fast
+- [ ] Lazy loading reduces initial overhead
+
+### 8. Security
+- [ ] API keys are never logged
+- [ ] Webhook signatures are verified
+- [ ] Input validation prevents injection
+- [ ] HTTPS is enforced
+- [ ] Sensitive data is not exposed in errors
+
+### 9. Testing
+- [ ] Core modules have unit tests
+- [ ] Services have integration tests
+- [ ] Coverage meets targets (80%+)
+- [ ] Tests are maintainable
+- [ ] CI/CD runs tests automatically
+
+### 10. Documentation
+- [ ] README is comprehensive
+- [ ] API reference is complete
+- [ ] Examples cover common use cases
+- [ ] Migration guides exist
+- [ ] Changelog is maintained
+
+## Review Process
+
+1. **Automated Checks**
+   - Run TypeScript compiler
+   - Run linter
+   - Run test suite
+   - Check coverage
+   - Analyze bundle size
+
+2. **Manual Review**
+   - Review code structure
+   - Test API ergonomics
+   - Validate examples
+   - Check documentation
+   - Compare with competitors
+
+3. **Stakeholder Review**
+   - Backend Engineer: Technical correctness
+   - QA Engineer: Test coverage and quality
+   - Product Manager: DX and completeness
+
+4. **Report Findings**
+   - List critical issues (blockers)
+   - List major issues (should fix)
+   - List minor issues (nice to fix)
+   - List improvements (future)
+
+## Architecture Red Flags
+
+### Critical (Must Fix Before Release)
+- ❌ TypeScript errors in strict mode
+- ❌ Security vulnerabilities
+- ❌ Breaking API inconsistencies
+- ❌ Data loss in transformations
+- ❌ Memory leaks
+- ❌ Unhandled error cases
+
+### Major (Should Fix Before Release)
+- ⚠️ Poor error messages
+- ⚠️ Missing critical tests
+- ⚠️ Inconsistent naming
+- ⚠️ Large bundle size
+- ⚠️ Slow performance
+- ⚠️ Incomplete documentation
+
+### Minor (Can Fix in Patch)
+- ℹ️ Suboptimal code structure
+- ℹ️ Missing JSDoc
+- ℹ️ Redundant code
+- ℹ️ Minor DX issues
+
+## Architecture Best Practices Checklist
+
+### General
+- [ ] Follows SOLID principles
+- [ ] DRY (Don't Repeat Yourself)
+- [ ] KISS (Keep It Simple, Stupid)
+- [ ] YAGNI (You Aren't Gonna Need It)
+- [ ] Composition over inheritance
+
+### TypeScript Specific
+- [ ] Strict mode enabled
+- [ ] Types exported for consumers
+- [ ] Generics used appropriately
+- [ ] Union types for variants
+- [ ] Branded types for IDs
+
+### SDK Specific
+- [ ] Client is immutable
+- [ ] Configuration is validated
+- [ ] Requests are retryable
+- [ ] Responses are typed
+- [ ] Errors are structured
+
+### Async/Promises
+- [ ] All async functions return promises
+- [ ] Errors are caught appropriately
+- [ ] No unhandled promise rejections
+- [ ] Timeouts are configurable
+- [ ] Cancellation is supported (if needed)
+
+## Comparative Analysis
+
+### vs. Polar SDK
+- What patterns are we following?
+- What are we doing differently?
+- Are our deviations justified?
+
+### vs. Stripe SDK
+- How does DX compare?
+- Are we missing critical features?
+- What can we learn?
+
+### vs. Industry Standards
+- Do we follow REST conventions?
+- Is our API idiomatic?
+- Are we using modern patterns?
+
+## Review Outcome
+
+### Go (Ready for Release)
+All critical issues resolved, major issues have workarounds or are acceptable, documentation is complete.
+
+### Go with Conditions
+Most issues resolved, remaining issues documented and accepted as technical debt, release notes include known limitations.
+
+### No-Go (Not Ready)
+Critical issues remain, major quality concerns, incomplete implementation, insufficient testing.
+
+## Example Review Report
+
+```markdown
+# Architecture Review Report
+Date: 2025-11-10
+Reviewer: [Agent Name]
+Version: 0.1.0
+
+## Summary
+Overall architecture is solid, following Polar SDK patterns effectively. Found 2 critical issues, 5 major issues, and 8 minor issues.
+
+## Critical Issues (Must Fix)
+1. **Type Error in Encodings** - File: src/lib/encodings.ts:42
+   - Issue: Type mismatch in outbound schema
+   - Impact: Runtime errors for API calls
+   - Fix: Update type definition
+
+## Major Issues (Should Fix)
+1. **Missing Retry Tests** - File: src/lib/retries.ts
+   - Issue: Retry logic not tested with failure scenarios
+   - Impact: Untested behavior in production
+   - Fix: Add integration tests
+
+## Minor Issues (Nice to Fix)
+1. **Missing JSDoc** - File: src/sdk/customers.ts
+   - Issue: Some methods lack documentation
+   - Impact: Reduced DX
+   - Fix: Add JSDoc comments
+
+## Recommendations
+1. Follow up on critical issues immediately
+2. Address major issues before beta release
+3. Create tickets for minor issues
+
+## Conclusion
+**Status: Go with Conditions**
+Ready for alpha release after fixing 2 critical issues. Major issues can be addressed in beta.
+```
+
+## Usage
+
+```bash
+# Run architecture review
+claude --agent product-manager --prompt .claude/prompts/sdk-architecture-review.md
+
+# Or manually invoke
+# Read this prompt and conduct the review following all sections
+```

package/.claude/settings.local.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)",
+      "Bash(find:*)",
+      "Bash(for file in CONTRIBUTING.md USAGE.md FUNCTIONS.md RELEASES.md RUNTIMES.md)",
+      "Bash(do [ -f \"$file\" ]:*)",
+      "Bash(done)",
+      "Bash(npm run lint:*)",
+      "Bash(npm install:*)",
+      "Bash(npm run build:*)",
+      "Bash(npx tsx:*)",
+      "Bash(node -e:*)",
+      "Bash(export CHARGEFY_ACCESS_TOKEN:*)",
+      "Bash(cat:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}