@sudobility/mail_box_types 1.0.10 → 1.0.12

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.
Files changed (2) hide show
  1. package/CLAUDE.md +225 -166
  2. package/package.json +3 -3
package/CLAUDE.md CHANGED
@@ -1,227 +1,286 @@
1
- # CLAUDE.md - AI Development Guide
1
+ # mail_box_types - AI Development Guide
2
2
 
3
- This file provides comprehensive guidance for AI assistants (Claude Code, GitHub Copilot, Cursor, etc.) working with this codebase.
3
+ ## Overview
4
4
 
5
- ## Project Overview
5
+ `@sudobility/mail_box_types` is a TypeScript types-only library that provides comprehensive type definitions, enums, type guards, and helper functions for the Mail Box protocol. It covers four domains: the blockchain Indexer API, the WildDuck mail server (REST and WebSocket), KYC/Sumsub identity verification, and multi-chain mailbox smart contract interactions (EVM and Solana). All runtime values (enums, type guards, factory functions) are shipped alongside pure type definitions.
6
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`.
7
+ - **Package**: `@sudobility/mail_box_types`
8
+ - **Version**: 1.0.10
9
+ - **License**: BUSL-1.1
10
+ - **Package Manager**: Bun (always use `bun` commands, never `npm`)
11
+ - **Module Format**: Dual ESM (`dist/index.js`) + CommonJS (`dist/index.cjs`) with TypeScript declarations (`dist/index.d.ts`)
24
12
 
25
13
  ## Project Structure
26
14
 
27
15
  ```
28
16
  src/
29
- ├── index.ts # Main entry point, re-exports all types
17
+ ├── index.ts # Root entry point, re-exports ./types
30
18
  └── types/
31
- ├── index.ts # Aggregates all type modules
19
+ ├── index.ts # Aggregates and re-exports all 4 modules
32
20
  ├── 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
21
+ │ ├── index.ts # Named re-exports of all indexer types & guards
22
+ │ ├── indexer-responses.ts # ~50 interfaces/types for Indexer API responses
23
+ │ ├── indexer-guards.ts # 22 runtime type guard functions
24
+ │ └── indexer-guards.test.ts # Tests for indexer type guards
36
25
  ├── 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
26
+ │ ├── index.ts # Re-exports REST + WebSocket types
27
+ │ ├── wildduck-types.ts # ~80 interfaces for WildDuck REST API
28
+ │ ├── wildduck-websocket-types.ts # ~50 interfaces for WildDuck WebSocket API
29
+ │ ├── wildduck-types.test.ts # Tests for REST type guards & helpers
30
+ │ └── wildduck-websocket-types.test.ts # Tests for WebSocket type guards & helpers
40
31
  ├── kyc/
41
- │ ├── index.ts # Exports all KYC types
42
- │ └── kyc-types.ts # KYC verification types (Sumsub integration)
32
+ │ ├── index.ts # Re-exports KYC types
33
+ │ ├── kyc-types.ts # ~25 interfaces + 6 enums for KYC/Sumsub
34
+ │ └── kyc-types.test.ts # Tests for KYC enums & types
43
35
  └── mailer/
44
- ├── index.ts # Exports all mailer types
45
- └── mail-types.ts # Mailbox contract response types
36
+ ├── index.ts # Re-exports mailer types
37
+ ├── mail-types.ts # ~25 interfaces + 3 enums for contract responses
38
+ └── mail-types.test.ts # Tests for mailer type guards & enums
46
39
  ```
47
40
 
48
- ## Package Manager
41
+ ## Key Type Categories
42
+
43
+ ### Indexer Types (`types/indexer/`)
49
44
 
50
- **This project uses Bun as the package manager.** Always use `bun` commands instead of `npm`:
45
+ API response types for the Mail Box Indexer service. Every response wraps data via `ApiResponse<T>` from `@sudobility/types`.
46
+
47
+ | Category | Key Types |
48
+ |----------|-----------|
49
+ | Email Accounts | `IndexerNameServiceAccount`, `IndexerWalletAccount`, `IndexerEmailAccountsResponse` |
50
+ | Rewards / Points | `IndexerRewardData`, `IndexerRewardsResponse`, `IndexerPointsData`, `IndexerPointsResponse`, `IndexerLeaderboardResponse` |
51
+ | Delegation | `IndexerDelegateData`, `IndexerDelegatedToResponse`, `IndexerDelegatedFromResponse` |
52
+ | Name Service | `IndexerNameServiceData`, `IndexerNameResolutionData` |
53
+ | Address Validation | `IndexerAddressValidationData`, `IndexerAddressValidationResponse` |
54
+ | Entitlement | `IndexerEntitlementInfo`, `IndexerEntitlementResponse` |
55
+ | Authentication | `IndexerAuthenticationStatusData`, `IndexerSignInMessageData`, `IndexerNonceData` |
56
+ | Referrals | `IndexerReferralCodeData`, `IndexerReferralStatsData` |
57
+ | Block Status | `IndexerChainBlockInfo`, `IndexerBlockStatusData` |
58
+ | Site Stats | `IndexerSiteStatsData`, `IndexerSiteStatsResponse` |
59
+ | Templates | `IndexerTemplateData`, `IndexerTemplateCreateRequest`, `IndexerTemplateUpdateRequest` |
60
+ | Webhooks | `IndexerWebhookData`, `IndexerWebhookCreateRequest` |
61
+ | Error | `IndexerErrorResponse` |
62
+ | Union | `IndexerApiResponse` (union of all response types) |
63
+
64
+ **Type guards** (22 functions): `isEmailAccountsResponse`, `isRewardsResponse`, `isDelegatedToResponse`, `isIndexerErrorResponse`, `isIndexerSuccessResponse`, etc.
65
+
66
+ ### WildDuck REST Types (`types/wildduck/wildduck-types.ts`)
67
+
68
+ Comprehensive types matching the WildDuck Mail Server API specification.
69
+
70
+ | Category | Key Types |
71
+ |----------|-----------|
72
+ | Config | `WildduckConfig`, `WildduckObjectId` |
73
+ | Authentication | `WildduckPreAuthRequest/Response`, `WildduckAuthenticateRequest`, `WildduckAuthResponse`, `WildduckUserAuth` |
74
+ | Users | `WildduckUser`, `WildduckUserResponse`, `WildduckCreateUserRequest/Response`, `WildduckUpdateUserRequest`, `WildduckUserListResponse` |
75
+ | Mailboxes | `WildduckMailbox`, `WildduckMailboxResponse`, `MailboxSpecialUse` (enum), `EmailFolder`, `EmailFolderUtils` |
76
+ | Messages | `WildduckMessageListItem`, `WildduckMessageDetail`, `WildduckMessagesResponse`, `WildduckSearchMessagesRequest/Response` |
77
+ | Message Ops | `WildduckUploadMessageRequest/Response`, `WildduckSubmitMessageRequest/Response`, `WildduckUpdateMessageRequest/Response` |
78
+ | Addresses | `WildduckAddress`, `WildduckAddressListResponse`, `WildduckCreateAddressRequest/Response`, `WildduckForwardedAddressListItem` |
79
+ | Filters | `FilterQuery`, `FilterAction`, `WildduckFilterListItem`, `WildduckCreateFilterRequest/Response` |
80
+ | Autoreply | `WildduckAutoreplyRequest`, `WildduckAutoreplyResponse` |
81
+ | ASP | `WildduckASPListItem`, `WildduckCreateASPRequest/Response` |
82
+ | Storage | `WildduckStorageUploadRequest/Response`, `WildduckStorageListItem` |
83
+ | Settings | `WildduckSettingItem`, `WildduckSettingsListResponse`, `UserInfo`, `AutoReplySettings`, `SpamSettings`, `AdvancedSettings`, `SMTPRelay` |
84
+ | DKIM | `WildduckDKIMListItem`, `WildduckCreateDKIMRequest/Response` |
85
+ | Webhooks | `WildduckWebhookListItem`, `WildduckCreateWebhookRequest/Response` |
86
+ | Audit | `WildduckCreateAuditRequest/Response`, `WildduckAuditResponse` |
87
+ | Health | `WildduckHealthResponse` |
88
+ | Common | `WildduckPaginationParams`, `WildduckSessionParams`, `WildduckLimits`, `WildduckSuccessResponse`, `WildduckDeleteResponse`, `WildduckErrorResponse` |
89
+
90
+ **Enum**: `MailboxSpecialUse` (Inbox, Sent, Trash, Drafts, Junk, Settings, Developer)
91
+
92
+ **Helper objects**: `EmailFolderUtils` (isStandardFolder, getStandardFolders, isCustomFolder, displayName)
93
+
94
+ **Factory functions**: `createPreAuthRequest()`, `createAuthenticateRequest()`
95
+
96
+ **Type guards**: `isWildduckAuthResponse()`, `isWildduckMessage()`
97
+
98
+ ### WildDuck WebSocket Types (`types/wildduck/wildduck-websocket-types.ts`)
99
+
100
+ Real-time WebSocket communication types for five channels: `mailboxes`, `settings`, `filters`, `autoreply`, `messages`.
101
+
102
+ | Category | Key Types |
103
+ |----------|-----------|
104
+ | Channels | `WildduckWebSocketChannel`, `WildduckWebSocketMessageType` |
105
+ | Base | `WildduckWebSocketMessage<T>`, `WildduckWebSocketAuthData`, `WildduckWebSocketResponseData<T>` |
106
+ | Client Requests | `WildduckSubscribeRequest` (union), `WildduckUnsubscribeRequest`, `WildduckFetchMessagesRequest`, `WildduckWebSocketClientMessage` (union) |
107
+ | Data Responses | `WildduckMailboxesDataResponse`, `WildduckSettingsDataResponse`, `WildduckFiltersDataResponse`, `WildduckAutoreplyDataResponse`, `WildduckMessagesDataResponse` |
108
+ | Data Messages | `WildduckWebSocketDataMessage` (union of all channel data messages) |
109
+ | Update Events | `WildduckMailboxUpdateEvent`, `WildduckMessageUpdateEvent`, `WildduckSettingsUpdateEvent`, `WildduckFilterUpdateEvent`, `WildduckAutoreplyUpdateEvent` |
110
+ | Update Messages | `WildduckWebSocketUpdateMessage` (union) |
111
+ | Disconnect | `WildduckDisconnectMessage` |
112
+ | All Messages | `WildduckWebSocketServerMessage` (union), `WildduckAnyWebSocketMessage` (union) |
113
+
114
+ **Type guards**: `isWildduckSubscribeRequest()`, `isWildduckUnsubscribeRequest()`, `isWildduckFetchRequest()`, `isWildduckDataMessage()`, `isWildduckUpdateMessage()`, `isWildduckDisconnectMessage()`, `isWildduckWebSocketErrorResponse()`
115
+
116
+ **Factory functions**: `createWildduckSubscribeRequest()`, `createWildduckUnsubscribeRequest()`, `createWildduckFetchMessagesRequest()`
117
+
118
+ ### KYC Types (`types/kyc/kyc-types.ts`)
119
+
120
+ Know Your Customer verification types integrating with Sumsub for three-tier identity verification (Basic, Enhanced, Accredited).
121
+
122
+ | Category | Key Types |
123
+ |----------|-----------|
124
+ | Enums | `KYCVerificationLevel`, `KYCApplicationStatus`, `SumsubReviewStatus`, `SumsubReviewAnswer`, `ApplicantType`, `ReviewRejectType` |
125
+ | DB Models | `KYCApplication`, `VerificationResult`, `UserConsent` |
126
+ | Sumsub API | `SumsubConfig`, `SumsubApplicantData`, `SumsubWebhookPayload`, `SumsubApplicantStatus` |
127
+ | API Requests | `InitiateKYCRequest`, `VerifyUserRequest`, `RevokeConsentRequest` |
128
+ | API Responses | `InitiateKYCResponse`, `GetKYCStatusResponse`, `VerificationLevelStatus`, `VerifyUserResponse`, `RevokeConsentResponse`, `GetConsentsResponse` |
129
+
130
+ ### Mailer Types (`types/mailer/mail-types.ts`)
131
+
132
+ Mailbox smart contract response types for multi-chain (EVM + Solana) messaging.
133
+
134
+ | Category | Key Types |
135
+ |----------|-----------|
136
+ | Enums | `ConfirmationStatus` (Processed/Confirmed/Finalized), `ClaimType` (Recipient/Owner/Expired), `FeeType` (Send/Delegation/Registration) |
137
+ | Core Responses | `BaseTransactionResponse`, `TransactionReceipt` |
138
+ | Message Ops | `MessageSendResponse`, `PreparedMessageSendResponse` |
139
+ | Revenue & Claims | `ClaimableInfo`, `ClaimRevenueResponse`, `ClaimableAmountResponse` |
140
+ | Domain & Delegation | `DomainRegistrationResponse`, `MailboxDelegationResponse`, `DelegationRejectionResponse` |
141
+ | Fee Management | `FeeInfo`, `FeeUpdateResponse` |
142
+ | Contract State | `PauseInfo`, `PauseResponse`, `EmergencyDistributionResponse` |
143
+ | Chain-Specific | `EVMTransactionResponse`, `SolanaTransactionResponse` |
144
+ | Client Types | `UnifiedClientResponse<T>`, `BatchOperationResponse` |
145
+ | Query Types | `MessageHistoryItem`, `MessageHistoryResponse`, `DelegationStatusResponse` |
146
+ | Error | `ContractError` (alias for `UnifiedError`) |
147
+
148
+ **Type guards**: `isEVMResponse()`, `isSolanaResponse()`, `isMailboxErrorResponse()`, `isConfirmationStatus()`, `isClaimType()`, `isFeeType()`, `isBaseTransactionResponse()`, `isMessageSendResponse()`, `isClaimableInfo()`
149
+
150
+ ## Development Commands
51
151
 
52
152
  ```bash
53
153
  # Install dependencies
54
154
  bun install
55
155
 
56
- # Run any script
57
- bun run <script-name>
58
- ```
156
+ # Type checking (no emit)
157
+ bun run typecheck
59
158
 
60
- ## Key Commands
159
+ # Linting
160
+ bun run lint
161
+ bun run lint:fix
61
162
 
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
- ```
163
+ # Formatting
164
+ bun run format
165
+ bun run format:check
74
166
 
75
- ## Development Guidelines
167
+ # Testing
168
+ bun run test # Run all tests (Vitest)
169
+ bun run test:watch # Watch mode
170
+ bun run test:coverage # Coverage report (v8 provider)
76
171
 
77
- ### Export Conventions
172
+ # Building
173
+ bun run build # Build ESM + CJS outputs
174
+ bun run clean # Remove dist/
78
175
 
79
- **All types must be exported as named exports.** No default exports.
176
+ # Full verification pipeline
177
+ bun run verify # typecheck + lint + test + build
80
178
 
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 { ... }
179
+ # Dev mode
180
+ bun run dev # tsc --watch
90
181
  ```
91
182
 
92
- ### Import from @sudobility/types
183
+ ## Architecture / Patterns
93
184
 
94
- For common types, import directly from `@sudobility/types`:
185
+ ### Module Organization
95
186
 
96
- ```typescript
97
- import type { Optional, BaseResponse, MessageBase } from '@sudobility/types';
98
- import { ChainType } from '@sudobility/types';
99
- ```
187
+ Each type domain lives in its own subdirectory under `src/types/` with a consistent structure:
188
+ - `*-types.ts` -- Interfaces, type aliases, enums, factory functions
189
+ - `*-guards.ts` -- Runtime type guard functions (indexer only; other modules co-locate guards)
190
+ - `index.ts` -- Named re-exports for the module
191
+ - `*.test.ts` -- Vitest tests co-located alongside source
192
+
193
+ The root `src/types/index.ts` barrel-exports all four modules, and `src/index.ts` re-exports that barrel.
100
194
 
101
- ### Type Organization
195
+ ### Naming Conventions
102
196
 
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`)
197
+ - **Interfaces**: PascalCase, prefixed by domain (`Indexer*`, `Wildduck*`, `KYC*`)
198
+ - **Enums**: PascalCase with PascalCase members (e.g., `MailboxSpecialUse.Inbox`, `ConfirmationStatus.Finalized`)
199
+ - **Type guards**: camelCase, prefixed with `is` (e.g., `isEVMResponse`, `isIndexerErrorResponse`)
200
+ - **Factory/helper functions**: camelCase, prefixed with `create` (e.g., `createPreAuthRequest`, `createWildduckSubscribeRequest`)
201
+ - **Request types**: `*Request` suffix
202
+ - **Response types**: `*Response` suffix
203
+ - **List items**: `*ListItem` suffix for paginated result entries
107
204
 
108
- ### File Naming
205
+ ### Export Conventions
109
206
 
110
- - `*-types.ts` - Type definitions
111
- - `*-guards.ts` - Type guard functions
112
- - `index.ts` - Re-exports for the module
207
+ All exports are **named exports only** -- no default exports. Types are exported with `export type` or `export interface`; runtime values use `export function`, `export enum`, or `export const`.
113
208
 
114
- ### Common Patterns
209
+ ### API Response Pattern
115
210
 
116
- **API Response Pattern**:
211
+ Indexer responses use the generic `ApiResponse<T>` wrapper from `@sudobility/types`:
117
212
  ```typescript
118
- export interface MyDataResult {
119
- // actual data fields
120
- }
121
- export type MyResponse = ApiResponse<MyDataResult>;
213
+ export interface IndexerPointsData extends WalletData { ... }
214
+ export type IndexerPointsResponse = ApiResponse<IndexerPointsData>;
122
215
  ```
123
216
 
124
- **Type Guard Pattern**:
217
+ WildDuck responses use a simpler `{ success: boolean; ... }` pattern.
218
+
219
+ Mailer responses extend `TransactionReceipt` (which extends `BaseTransactionResponse`) for blockchain operations, and `BaseResponse<T>` / `PaginatedResponse<T>` from `@sudobility/types` for client-facing queries.
220
+
221
+ ### Type Guard Pattern
222
+
125
223
  ```typescript
126
224
  export function isMyResponse(response: unknown): response is MyResponse {
127
225
  return !!(
128
226
  response &&
129
227
  typeof response === 'object' &&
130
- 'success' in response &&
131
- // ... additional checks
228
+ 'requiredField' in response &&
229
+ // ...additional discriminant checks
132
230
  );
133
231
  }
134
232
  ```
135
233
 
136
- ## Build Output
234
+ ### TypeScript Configuration
137
235
 
138
- The project builds to:
139
- - `dist/index.js` - ESM module
140
- - `dist/index.cjs` - CommonJS module
141
- - `dist/index.d.ts` - TypeScript declarations
236
+ - **Target**: ES2020
237
+ - **Strict mode**: Enabled
238
+ - **Module resolution**: `bundler` (base), `ESNext` (ESM build), `CommonJS`/`node` (CJS build)
239
+ - **Declarations**: Generated for ESM build only (with source maps and declaration maps)
240
+ - Tests (`*.test.ts`, `*.spec.ts`) are excluded from compilation
142
241
 
143
- Package.json exports configuration supports both ESM and CJS consumers.
242
+ ### Code Style
144
243
 
145
- ## Type Categories
244
+ Configured via Prettier (`.prettierrc`): single quotes, semicolons, trailing commas `es5`, 80-char print width, 2-space indentation. ESLint uses `@typescript-eslint` with `no-explicit-any` as warning, `no-unused-vars` ignoring `_`-prefixed args.
146
245
 
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
246
+ ## Common Tasks
157
247
 
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.
248
+ ### Adding a New Type to an Existing Module
197
249
 
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
- ```
250
+ 1. Edit the appropriate `*-types.ts` file in `src/types/<module>/`
251
+ 2. Define interfaces/types/enums as named exports
252
+ 3. Import shared types from `@sudobility/types` (e.g., `Optional`, `ChainType`, `ApiResponse`, `WalletData`)
253
+ 4. Add re-exports to the module's `index.ts`
254
+ 5. If adding type guards, follow the `is*` prefix convention
255
+ 6. Write tests in the corresponding `*.test.ts` file
256
+ 7. Verify: `bun run typecheck && bun run lint && bun run test`
257
+ 8. Build: `bun run build`
203
258
 
204
- ### Test Files
259
+ ### Adding a New Type Module
205
260
 
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
261
+ 1. Create a new directory under `src/types/` (e.g., `src/types/newmodule/`)
262
+ 2. Create `newmodule-types.ts` with interfaces, enums, and type guards
263
+ 3. Create `index.ts` that re-exports everything from `newmodule-types.ts`
264
+ 4. Add `export * from './newmodule';` to `src/types/index.ts`
265
+ 5. Create `newmodule-types.test.ts` with tests for enums, type guards, and helpers
266
+ 6. Run `bun run verify`
211
267
 
212
- ### What to Test
268
+ ### Testing Guidelines
213
269
 
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
270
+ Tests use Vitest with global test functions (`describe`, `it`, `expect`) and are co-located with source. Coverage excludes `index.ts` barrel files. Focus areas:
271
+ 1. **Type guards** -- valid and invalid inputs
272
+ 2. **Factory functions** -- correct default values and overrides
273
+ 3. **Enums** -- verify string values match expected constants
274
+ 4. **Type compatibility** -- ensure interfaces can be instantiated correctly
218
275
 
219
- ## Adding New Types
276
+ ## Peer / Key Dependencies
220
277
 
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
278
+ | Dependency | Role |
279
+ |-----------|------|
280
+ | `@sudobility/types` (peer, ^1.9.51) | Shared utility types: `Optional`, `ChainType`, `WalletData`, `ApiResponse`, `BaseResponse`, `PaginatedResponse`, `MessageBase`, `UnifiedError` |
281
+ | `typescript` (dev, ^5.9.3) | TypeScript compiler |
282
+ | `vitest` (dev, ^4.0.16) | Test runner |
283
+ | `@vitest/coverage-v8` (dev) | Coverage provider |
284
+ | `eslint` + `@typescript-eslint/*` (dev) | Linting |
285
+ | `prettier` (dev) | Code formatting |
286
+ | `rimraf` (dev) | Clean script |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sudobility/mail_box_types",
3
- "version": "1.0.10",
3
+ "version": "1.0.12",
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",
@@ -47,7 +47,7 @@
47
47
  "license": "BUSL-1.1",
48
48
  "devDependencies": {
49
49
  "@eslint/js": "^9.38.0",
50
- "@sudobility/types": "^1.9.51",
50
+ "@sudobility/types": "^1.9.53",
51
51
  "@types/node": "^24.9.1",
52
52
  "@typescript-eslint/eslint-plugin": "^8.46.2",
53
53
  "@typescript-eslint/parser": "^8.46.2",
@@ -60,7 +60,7 @@
60
60
  "vitest": "^4.0.16"
61
61
  },
62
62
  "peerDependencies": {
63
- "@sudobility/types": "^1.9.51"
63
+ "@sudobility/types": "^1.9.53"
64
64
  },
65
65
  "publishConfig": {
66
66
  "access": "public"