@sudobility/mail_box_types 1.0.2 → 1.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +227 -0
- package/package.json +12 -10
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
# CLAUDE.md - AI Development Guide
|
|
2
|
+
|
|
3
|
+
This file provides comprehensive guidance for AI assistants (Claude Code, GitHub Copilot, Cursor, etc.) working with this codebase.
|
|
4
|
+
|
|
5
|
+
## Project Overview
|
|
6
|
+
|
|
7
|
+
`@sudobility/mail_box_types` is a TypeScript types library providing comprehensive type definitions for Mail Box services.
|
|
8
|
+
|
|
9
|
+
**Package**: `@sudobility/mail_box_types`
|
|
10
|
+
**Version**: 1.0.2
|
|
11
|
+
**Type**: ES Module + CommonJS
|
|
12
|
+
**Test Coverage**: 202 tests across 5 test files
|
|
13
|
+
|
|
14
|
+
The library provides:
|
|
15
|
+
|
|
16
|
+
- **Indexer API types**: API responses and type guards for the Mail Box Indexer service
|
|
17
|
+
- **WildDuck types**: Mail server API types including REST and WebSocket interfaces
|
|
18
|
+
- **KYC types**: Know Your Customer verification types for Sumsub integration
|
|
19
|
+
- **Mailer types**: Mailbox contract response types for multi-chain messaging (EVM and Solana)
|
|
20
|
+
|
|
21
|
+
## Dependencies
|
|
22
|
+
|
|
23
|
+
This package depends on `@sudobility/types` for common utility types. Common types like `Optional`, `ChainType`, `BaseResponse`, etc. are re-exported from `@sudobility/types`.
|
|
24
|
+
|
|
25
|
+
## Project Structure
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
src/
|
|
29
|
+
├── index.ts # Main entry point, re-exports all types
|
|
30
|
+
└── types/
|
|
31
|
+
├── index.ts # Aggregates all type modules
|
|
32
|
+
├── indexer/
|
|
33
|
+
│ ├── index.ts # Exports all indexer types and guards
|
|
34
|
+
│ ├── indexer-responses.ts # API response type definitions
|
|
35
|
+
│ └── indexer-guards.ts # Runtime type guard functions
|
|
36
|
+
├── wildduck/
|
|
37
|
+
│ ├── index.ts # Exports all WildDuck types
|
|
38
|
+
│ ├── wildduck-types.ts # REST API types (users, mailboxes, messages, etc.)
|
|
39
|
+
│ └── wildduck-websocket-types.ts # WebSocket API types
|
|
40
|
+
├── kyc/
|
|
41
|
+
│ ├── index.ts # Exports all KYC types
|
|
42
|
+
│ └── kyc-types.ts # KYC verification types (Sumsub integration)
|
|
43
|
+
└── mailer/
|
|
44
|
+
├── index.ts # Exports all mailer types
|
|
45
|
+
└── mail-types.ts # Mailbox contract response types
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Package Manager
|
|
49
|
+
|
|
50
|
+
**This project uses Bun as the package manager.** Always use `bun` commands instead of `npm`:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
# Install dependencies
|
|
54
|
+
bun install
|
|
55
|
+
|
|
56
|
+
# Run any script
|
|
57
|
+
bun run <script-name>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Key Commands
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
bun run build # Build ESM and CJS outputs
|
|
64
|
+
bun run typecheck # Run TypeScript compiler (no emit)
|
|
65
|
+
bun run lint # Run ESLint
|
|
66
|
+
bun run lint:fix # Run ESLint with auto-fix
|
|
67
|
+
bun run format # Format code with Prettier
|
|
68
|
+
bun run format:check # Check formatting
|
|
69
|
+
bun run test # Run all tests
|
|
70
|
+
bun run test:watch # Run tests in watch mode
|
|
71
|
+
bun run test:coverage # Run tests with coverage report
|
|
72
|
+
bun run clean # Remove dist folder
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Development Guidelines
|
|
76
|
+
|
|
77
|
+
### Export Conventions
|
|
78
|
+
|
|
79
|
+
**All types must be exported as named exports.** No default exports.
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
// Correct
|
|
83
|
+
export interface MyType { ... }
|
|
84
|
+
export type MyAlias = ...;
|
|
85
|
+
export enum MyEnum { ... }
|
|
86
|
+
export function myGuard(x: unknown): x is MyType { ... }
|
|
87
|
+
|
|
88
|
+
// Incorrect - DO NOT USE
|
|
89
|
+
export default interface MyType { ... }
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Import from @sudobility/types
|
|
93
|
+
|
|
94
|
+
For common types, import directly from `@sudobility/types`:
|
|
95
|
+
|
|
96
|
+
```typescript
|
|
97
|
+
import type { Optional, BaseResponse, MessageBase } from '@sudobility/types';
|
|
98
|
+
import { ChainType } from '@sudobility/types';
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Type Organization
|
|
102
|
+
|
|
103
|
+
1. **Interfaces/Types**: Define data structures
|
|
104
|
+
2. **Enums**: Define fixed sets of values
|
|
105
|
+
3. **Type Guards**: Runtime type checking functions (prefix with `is`)
|
|
106
|
+
4. **Helper Functions**: Factory functions (prefix with `create`)
|
|
107
|
+
|
|
108
|
+
### File Naming
|
|
109
|
+
|
|
110
|
+
- `*-types.ts` - Type definitions
|
|
111
|
+
- `*-guards.ts` - Type guard functions
|
|
112
|
+
- `index.ts` - Re-exports for the module
|
|
113
|
+
|
|
114
|
+
### Common Patterns
|
|
115
|
+
|
|
116
|
+
**API Response Pattern**:
|
|
117
|
+
```typescript
|
|
118
|
+
export interface MyDataResult {
|
|
119
|
+
// actual data fields
|
|
120
|
+
}
|
|
121
|
+
export type MyResponse = ApiResponse<MyDataResult>;
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**Type Guard Pattern**:
|
|
125
|
+
```typescript
|
|
126
|
+
export function isMyResponse(response: unknown): response is MyResponse {
|
|
127
|
+
return !!(
|
|
128
|
+
response &&
|
|
129
|
+
typeof response === 'object' &&
|
|
130
|
+
'success' in response &&
|
|
131
|
+
// ... additional checks
|
|
132
|
+
);
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Build Output
|
|
137
|
+
|
|
138
|
+
The project builds to:
|
|
139
|
+
- `dist/index.js` - ESM module
|
|
140
|
+
- `dist/index.cjs` - CommonJS module
|
|
141
|
+
- `dist/index.d.ts` - TypeScript declarations
|
|
142
|
+
|
|
143
|
+
Package.json exports configuration supports both ESM and CJS consumers.
|
|
144
|
+
|
|
145
|
+
## Type Categories
|
|
146
|
+
|
|
147
|
+
### Common Types (from `@sudobility/types`)
|
|
148
|
+
Import directly from `@sudobility/types`:
|
|
149
|
+
- `Optional<T>` - Nullable utility type
|
|
150
|
+
- `ChainType` - Blockchain type enum (EVM, Solana)
|
|
151
|
+
- `WalletData` - Base wallet interface
|
|
152
|
+
- `ApiResponse<T>` - Standard API response wrapper
|
|
153
|
+
- `BaseResponse<T>` - Base response with required timestamp
|
|
154
|
+
- `PaginatedResponse<T>` - Paginated response structure
|
|
155
|
+
- `MessageBase` - Base message structure
|
|
156
|
+
- `UnifiedError` - Unified error structure
|
|
157
|
+
|
|
158
|
+
### Indexer Types (`types/indexer/`)
|
|
159
|
+
- Email account types
|
|
160
|
+
- Rewards/points types
|
|
161
|
+
- Delegation types
|
|
162
|
+
- Name service types
|
|
163
|
+
- Template and webhook types
|
|
164
|
+
- Type guards for all response types
|
|
165
|
+
|
|
166
|
+
### WildDuck Types (`types/wildduck/`)
|
|
167
|
+
- Authentication types
|
|
168
|
+
- User management types
|
|
169
|
+
- Mailbox types
|
|
170
|
+
- Message types (list, detail, search)
|
|
171
|
+
- Filter types
|
|
172
|
+
- WebSocket channel types and events
|
|
173
|
+
|
|
174
|
+
### KYC Types (`types/kyc/`)
|
|
175
|
+
- Verification level enums
|
|
176
|
+
- Application status enums
|
|
177
|
+
- Sumsub integration types
|
|
178
|
+
- Third-party DApp API types
|
|
179
|
+
|
|
180
|
+
### Mailer Types (`types/mailer/`)
|
|
181
|
+
Mailbox contract response types for multi-chain messaging:
|
|
182
|
+
- **Enums**: `ConfirmationStatus`, `ClaimType`, `FeeType`
|
|
183
|
+
- **Transaction Types**: `BaseTransactionResponse`, `TransactionReceipt`
|
|
184
|
+
- **Message Operations**: `MessageSendResponse`, `PreparedMessageSendResponse`
|
|
185
|
+
- **Revenue & Claims**: `ClaimableInfo`, `ClaimRevenueResponse`, `ClaimableAmountResponse`
|
|
186
|
+
- **Domain & Delegation**: `DomainRegistrationResponse`, `MailboxDelegationResponse`
|
|
187
|
+
- **Fee Management**: `FeeInfo`, `FeeUpdateResponse`
|
|
188
|
+
- **Contract State**: `PauseInfo`, `PauseResponse`, `EmergencyDistributionResponse`
|
|
189
|
+
- **Chain-Specific**: `EVMTransactionResponse`, `SolanaTransactionResponse`
|
|
190
|
+
- **Client Types**: `UnifiedClientResponse`, `BatchOperationResponse`
|
|
191
|
+
- **Query Types**: `MessageHistoryItem`, `MessageHistoryResponse`, `DelegationStatusResponse`
|
|
192
|
+
- **Type Guards**: `isEVMResponse`, `isSolanaResponse`, `isMailboxErrorResponse`, etc.
|
|
193
|
+
|
|
194
|
+
## Testing
|
|
195
|
+
|
|
196
|
+
Tests are written using Vitest and located alongside source files with `.test.ts` extension.
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
bun run test # Run all tests once
|
|
200
|
+
bun run test:watch # Run tests in watch mode
|
|
201
|
+
bun run test:coverage # Run tests with coverage
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
### Test Files
|
|
205
|
+
|
|
206
|
+
- `src/types/indexer/indexer-guards.test.ts` - Indexer type guard tests
|
|
207
|
+
- `src/types/wildduck/wildduck-types.test.ts` - WildDuck type guards and helpers
|
|
208
|
+
- `src/types/wildduck/wildduck-websocket-types.test.ts` - WebSocket type guards and helpers
|
|
209
|
+
- `src/types/kyc/kyc-types.test.ts` - KYC enum and type tests
|
|
210
|
+
- `src/types/mailer/mail-types.test.ts` - Mailer type guards and enum tests
|
|
211
|
+
|
|
212
|
+
### What to Test
|
|
213
|
+
|
|
214
|
+
1. **Type Guards**: Test that they correctly identify valid/invalid data
|
|
215
|
+
2. **Helper Functions**: Test factory functions produce correct structures
|
|
216
|
+
3. **Enums**: Verify enum values match expected strings
|
|
217
|
+
4. **Type Compatibility**: Ensure interfaces can be instantiated correctly
|
|
218
|
+
|
|
219
|
+
## Adding New Types
|
|
220
|
+
|
|
221
|
+
1. Create or edit the appropriate file in `src/types/<module>/`
|
|
222
|
+
2. Export all types as named exports
|
|
223
|
+
3. Import common types from `@sudobility/types`
|
|
224
|
+
4. Ensure the module's `index.ts` re-exports the new types
|
|
225
|
+
5. Add tests for type guards and helper functions in a corresponding `.test.ts` file
|
|
226
|
+
6. Run `bun run typecheck`, `bun run lint`, and `bun run test` to verify
|
|
227
|
+
7. Run `bun run build` to generate outputs
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sudobility/mail_box_types",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.4",
|
|
4
4
|
"description": "TypeScript types for Mail Box services - indexer, WildDuck, and KYC",
|
|
5
5
|
"main": "./dist/index.cjs",
|
|
6
6
|
"module": "./dist/index.js",
|
|
@@ -13,9 +13,9 @@
|
|
|
13
13
|
}
|
|
14
14
|
},
|
|
15
15
|
"scripts": {
|
|
16
|
-
"build": "
|
|
16
|
+
"build": "bun run build:esm && bun run build:cjs",
|
|
17
17
|
"build:esm": "tsc -p tsconfig.esm.json",
|
|
18
|
-
"build:cjs": "tsc -p tsconfig.cjs.json &&
|
|
18
|
+
"build:cjs": "tsc -p tsconfig.cjs.json && bun run build:cjs-rename",
|
|
19
19
|
"build:cjs-rename": "find dist -name '*.js' -not -name '*.cjs' -exec sh -c 'cp \"$1\" \"${1%.js}.cjs\"' _ {} \\;",
|
|
20
20
|
"clean": "rimraf dist",
|
|
21
21
|
"dev": "tsc --watch",
|
|
@@ -24,14 +24,16 @@
|
|
|
24
24
|
"format": "prettier --write \"src/**/*.{ts,js,json,md}\"",
|
|
25
25
|
"format:check": "prettier --check \"src/**/*.{ts,js,json,md}\"",
|
|
26
26
|
"typecheck": "tsc --noEmit",
|
|
27
|
-
"test": "vitest
|
|
28
|
-
"test:watch": "vitest",
|
|
29
|
-
"test:coverage": "vitest
|
|
30
|
-
"
|
|
27
|
+
"test": "vitest",
|
|
28
|
+
"test:watch": "vitest --watch",
|
|
29
|
+
"test:coverage": "vitest --coverage",
|
|
30
|
+
"verify": "bun run typecheck && bun run lint && bun run test && bun run build",
|
|
31
|
+
"prepublishOnly": "bun run clean && bun run verify"
|
|
31
32
|
},
|
|
32
33
|
"files": [
|
|
33
34
|
"dist/**/*",
|
|
34
|
-
"README.md"
|
|
35
|
+
"README.md",
|
|
36
|
+
"CLAUDE.md"
|
|
35
37
|
],
|
|
36
38
|
"keywords": [
|
|
37
39
|
"typescript",
|
|
@@ -45,7 +47,7 @@
|
|
|
45
47
|
"license": "MIT",
|
|
46
48
|
"devDependencies": {
|
|
47
49
|
"@eslint/js": "^9.38.0",
|
|
48
|
-
"@sudobility/types": "^1.9.
|
|
50
|
+
"@sudobility/types": "^1.9.44",
|
|
49
51
|
"@types/node": "^24.9.1",
|
|
50
52
|
"@typescript-eslint/eslint-plugin": "^8.46.2",
|
|
51
53
|
"@typescript-eslint/parser": "^8.46.2",
|
|
@@ -58,7 +60,7 @@
|
|
|
58
60
|
"vitest": "^4.0.16"
|
|
59
61
|
},
|
|
60
62
|
"peerDependencies": {
|
|
61
|
-
"@sudobility/types": "^1.9.
|
|
63
|
+
"@sudobility/types": "^1.9.44"
|
|
62
64
|
},
|
|
63
65
|
"publishConfig": {
|
|
64
66
|
"access": "public"
|