Skip to content

Commit 27141c9

Browse files
SmilefounderSmilefounder
committed
feat: Enhance README documentation with security best practices and configuration injection details across all packages
1 parent 28f6cf7 commit 27141c9

File tree

6 files changed

+196
-116
lines changed

6 files changed

+196
-116
lines changed

‎README.md‎

Lines changed: 40 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ Modular, framework-agnostic SDK for Mixcore projects. Built with TypeScript and
1010
- **TypeScript-first**: Full type safety and autocompletion
1111
- **Framework-agnostic**: Works with any JavaScript framework
1212
- **Production-ready**: Well-tested and documented
13+
- **Secure by design**: Configuration injection prevents hardcoded secrets
14+
- **Extensible**: Plugin/adapter architecture for custom implementations
1315

1416
## Packages
1517

@@ -32,18 +34,49 @@ Modular, framework-agnostic SDK for Mixcore projects. Built with TypeScript and
3234
npm install @mixcore/api @mixcore/database # or whichever packages you need
3335
```
3436

35-
### Usage Example
37+
### SDK Initialization
3638

3739
```typescript
40+
import { createMixcoreSdk } from '@mixcore/api';
3841
import { ApiService } from '@mixcore/api';
3942
import { ModuleDataService } from '@mixcore/database';
4043

41-
const api = new ApiService({ apiBaseUrl: 'https://api.mixcore.net' });
42-
const dataService = new ModuleDataService({ api });
43-
44-
// Use services...
44+
// Initialize SDK with configuration
45+
const sdk = createMixcoreSdk(
46+
{ apiBaseUrl: 'https://api.mixcore.net' },
47+
{
48+
api: new ApiService({ apiBaseUrl: 'https://api.mixcore.net' }),
49+
database: new ModuleDataService({ api: new ApiService({ apiBaseUrl: 'https://api.mixcore.net' }) })
50+
// Add other domain services as needed
51+
}
52+
);
53+
54+
// Use services through SDK instance
55+
const data = await sdk.database.fetchDataItems('module-id');
4556
```
4657

58+
### Security Note
59+
60+
- Never hardcode secrets in your application
61+
- Always inject configuration (API keys, URLs) at runtime
62+
- Use environment variables for sensitive values
63+
64+
## API Reference
65+
66+
### Core SDK Methods
67+
68+
| Method | Parameters | Returns | Description |
69+
|--------|------------|---------|-------------|
70+
| `createMixcoreSdk` | `config: MixcoreSdkConfig`, `services: MixcoreSdkOptions` | `MixcoreSdkInstance` | Creates configured SDK instance |
71+
72+
### Configuration Options
73+
74+
| Option | Type | Required | Description |
75+
|--------|------|----------|-------------|
76+
| `apiBaseUrl` | string | Yes | Base URL for API requests |
77+
| `apiKey` | string | No | API key for authentication |
78+
| `timeout` | number | No | Request timeout in ms |
79+
4780
## Development
4881

4982
### Prerequisites
@@ -71,6 +104,8 @@ pnpm build
71104
pnpm test
72105
```
73106

107+
Test coverage reports are generated in `coverage/` directory.
108+
74109
## Contributing
75110

76111
Contributions welcome! Please see our [Contribution Guidelines](CONTRIBUTING.md).

‎packages/api/README.md‎

Lines changed: 37 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ API clients and endpoint wrappers for Mixcore SDK. Provides typed HTTP clients f
99
- Built-in error handling
1010
- Support for authentication headers
1111
- Promise-based async operations
12+
- Secure configuration injection
13+
- Framework-agnostic implementation
1214

1315
## Installation
1416

@@ -27,50 +29,56 @@ import { ApiService } from '@mixcore/api';
2729

2830
const api = new ApiService({
2931
apiBaseUrl: 'https://api.mixcore.net',
30-
apiKey: 'your-api-key' // optional
32+
apiKey: process.env.MIXCORE_API_KEY // Never hardcode secrets!
3133
});
3234

3335
// Make API requests
3436
const response = await api.get('/some-endpoint');
3537
```
3638

39+
### SDK Entrypoint
40+
41+
```typescript
42+
import { createMixcoreSdk } from '@mixcore/api';
43+
44+
const sdk = createMixcoreSdk(
45+
{ apiBaseUrl: 'https://api.mixcore.net' },
46+
{
47+
api: new ApiService({ apiBaseUrl: 'https://api.mixcore.net' })
48+
}
49+
);
50+
```
51+
3752
### Configuration Options
3853

39-
| Option | Type | Description |
40-
|--------|------|-------------|
41-
| apiBaseUrl | string | Base URL for API requests |
42-
| apiKey? | string | API key for authentication |
43-
| timeout? | number | Request timeout in ms |
54+
| Option | Type | Required | Description |
55+
|--------|------|----------|-------------|
56+
| apiBaseUrl | string | Yes | Base URL for API requests |
57+
| apiKey? | string | No | API key for authentication |
58+
| timeout? | number | No | Request timeout in ms |
4459

45-
### Authentication
60+
### Security Note
4661

47-
```typescript
48-
// With API key
49-
const api = new ApiService({
50-
apiBaseUrl: 'https://api.mixcore.net',
51-
apiKey: 'your-api-key-here'
52-
});
62+
- Never hardcode API keys or secrets in your code
63+
- Always inject configuration at runtime
64+
- Use environment variables for sensitive values
5365

54-
// Requests will include Authorization: Bearer header
55-
```
66+
## API Reference
5667

57-
## Error Handling
68+
### ApiService Methods
5869

59-
The API client throws structured errors for:
70+
| Method | Parameters | Returns | Description |
71+
|--------|------------|---------|-------------|
72+
| get | `endpoint: string`, `params?: Record<string, any>` | `Promise<ApiResult>` | Makes GET request |
73+
| post | `endpoint: string`, `data: any`, `options?: { isFormData?: boolean }` | `Promise<ApiResult>` | Makes POST request |
74+
| delete | `endpoint: string` | `Promise<ApiResult>` | Makes DELETE request |
6075

61-
- Network failures
62-
- Invalid responses (non-2xx status codes)
63-
- Timeouts
76+
## Testing
6477

65-
```typescript
66-
try {
67-
await api.get('/some-endpoint');
68-
} catch (error) {
69-
console.error('API request failed:', error.message);
70-
if (error.response) {
71-
console.error('Status:', error.response.status);
72-
}
73-
}
78+
Test coverage reports are generated in `coverage/` directory when running:
79+
80+
```bash
81+
pnpm test
7482
```
7583

7684
## Related Packages

‎packages/base/README.md‎

Lines changed: 26 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Mixcore SDK base abstractions. Provides core TypeScript classes and interfaces f
88
- **BaseRestService**: REST API client base class
99
- **Injectable configuration**: Flexible service configuration
1010
- **Framework-agnostic**: No UI/SPA dependencies
11+
- **Secure by design**: Configuration injection prevents hardcoded secrets
1112

1213
## Installation
1314

@@ -37,39 +38,39 @@ class MyService extends BaseService {
3738
}
3839
```
3940

40-
### Using BaseRestService
41+
### Security Note
4142

42-
```typescript
43-
import { BaseRestService } from '@mixcore/base';
43+
- Never hardcode secrets in configuration
44+
- Always inject configuration at runtime
45+
- Use environment variables for sensitive values
4446

45-
class MyRestService extends BaseRestService {
46-
constructor(baseUrl: string) {
47-
super({ apiBaseUrl: baseUrl });
48-
}
47+
## API Reference
4948

50-
async fetchItems() {
51-
return this.get('/items');
52-
}
53-
}
54-
```
49+
### BaseService Methods
5550

56-
## API Reference
51+
| Method | Parameters | Returns | Description |
52+
|--------|------------|---------|-------------|
53+
| execute | `fn: () => Promise<T>` | `Promise<T>` | Wraps operations with error handling |
54+
| getConfig | None | `ConfigType` | Returns current configuration |
55+
56+
### BaseRestService Methods
57+
58+
| Method | Parameters | Returns | Description |
59+
|--------|------------|---------|-------------|
60+
| get | `path: string`, `params?: Record<string, any>` | `Promise<ApiResult>` | Makes GET request |
61+
| post | `path: string`, `data: any`, `options?: { isFormData?: boolean }` | `Promise<ApiResult>` | Makes POST request |
62+
| put | `path: string`, `data: any` | `Promise<ApiResult>` | Makes PUT request |
63+
| delete | `path: string` | `Promise<ApiResult>` | Makes DELETE request |
5764

58-
### BaseService
65+
## Testing
5966

60-
| Method | Description |
61-
|--------|-------------|
62-
| `execute(fn)` | Wraps operations with error handling |
63-
| `getConfig()` | Returns current configuration |
67+
Test coverage reports are generated in `coverage/` directory when running:
6468

65-
### BaseRestService
69+
```bash
70+
pnpm test
71+
```
6672

67-
| Method | Description |
68-
|--------|-------------|
69-
| `get(path)` | Makes GET request |
70-
| `post(path, data)` | Makes POST request |
71-
| `put(path, data)` | Makes PUT request |
72-
| `delete(path)` | Makes DELETE request |
73+
See test files in `tests/` directory for implementation details.
7374

7475
## Related Packages
7576

‎packages/config/README.md‎

Lines changed: 29 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Configuration management services for Mixcore SDK. Provides loading, validation
99
- Schema validation
1010
- Environment variable support
1111
- Hot-reloading for development
12+
- Secure by design: Prevents hardcoded secrets
1213

1314
## Installation
1415

@@ -27,47 +28,51 @@ import { ConfigurationServices } from '@mixcore/config';
2728

2829
const configService = new ConfigurationServices();
2930

30-
// Load config from default location
31-
const config = await configService.loadConfiguration();
31+
// Load config from environment variables
32+
const config = await configService.loadConfiguration({
33+
apiBaseUrl: process.env.MIXCORE_API_URL,
34+
apiKey: process.env.MIXCORE_API_KEY // Never hardcode secrets!
35+
});
3236

3337
// Access config values
3438
console.log(config.apiBaseUrl);
3539
```
3640

37-
### Custom Configuration Path
41+
### Security Best Practices
3842

39-
```typescript
40-
const config = await configService.loadConfiguration('/path/to/config.json');
41-
```
42-
43-
### Environment Variables
44-
45-
Configuration values can be overridden by environment variables prefixed with `MIXCORE_`:
46-
47-
```bash
48-
MIXCORE_API_BASE_URL=https://api.mixcore.net npm start
49-
```
43+
- Never commit configuration files with secrets
44+
- Use environment variables for sensitive values
45+
- Validate configuration schema in production
46+
- Rotate secrets regularly
5047

5148
## Configuration Schema
5249

53-
The expected configuration format:
54-
5550
```typescript
5651
interface AppConfig {
57-
apiBaseUrl: string;
58-
apiKey?: string;
59-
debug?: boolean;
52+
apiBaseUrl: string; // Required
53+
apiKey?: string; // Optional
54+
debug?: boolean; // Optional
6055
// ...other app-specific settings
6156
}
6257
```
6358

6459
## API Reference
6560

66-
| Method | Description |
67-
|--------|-------------|
68-
| `loadConfiguration(path?)` | Loads and validates config |
69-
| `getConfig()` | Returns current config |
70-
| `watchForChanges()` | Enables hot-reloading |
61+
| Method | Parameters | Returns | Description |
62+
|--------|------------|---------|-------------|
63+
| loadConfiguration | `config?: Partial<AppConfig>` | `Promise<AppConfig>` | Loads and validates config |
64+
| getConfig | None | `AppConfig` | Returns current config |
65+
| watchForChanges | None | `void` | Enables hot-reloading |
66+
67+
## Testing
68+
69+
Test coverage reports are generated in `coverage/` directory when running:
70+
71+
```bash
72+
pnpm test
73+
```
74+
75+
See test files in `tests/` directory for implementation details.
7176

7277
## Related Packages
7378

‎packages/database/README.md‎

Lines changed: 36 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Database domain services and types for Mixcore SDK. Provides data access, queryi
88
- TypeScript interfaces for database models
99
- Data validation and transformation
1010
- Modular service architecture
11+
- Secure configuration injection
1112

1213
## Installation
1314

@@ -22,25 +23,51 @@ pnpm add @mixcore/database
2223
### Basic Example
2324

2425
```typescript
26+
import { createMixcoreSdk } from '@mixcore/api';
2527
import { ModuleDataService } from '@mixcore/database';
26-
import { ApiService } from '@mixcore/api';
2728

28-
const api = new ApiService({ apiBaseUrl: 'https://api.mixcore.net' });
29-
const dataService = new ModuleDataService({ api });
29+
const sdk = createMixcoreSdk(
30+
{ apiBaseUrl: 'https://api.mixcore.net' },
31+
{
32+
database: new ModuleDataService({
33+
api: new ApiService({
34+
apiBaseUrl: 'https://api.mixcore.net',
35+
apiKey: process.env.MIXCORE_API_KEY // Never hardcode secrets!
36+
})
37+
})
38+
}
39+
);
3040

3141
// Fetch data items
32-
const result = await dataService.fetchDataItems('module-id');
42+
const result = await sdk.database.fetchDataItems('module-id');
3343
```
3444

35-
### Services
45+
### Security Note
3646

37-
- `ModuleDataService`: Core data operations
38-
- `MixDatabaseDataRestPortalService`: Portal-specific data services
39-
- `RelatedAttributeDataRestPortalService`: Related attribute services
47+
- Never hardcode API keys or secrets
48+
- Always inject configuration at runtime
49+
- Use environment variables for sensitive values
4050

4151
## API Reference
4252

43-
See [API Documentation](API.md) for detailed method signatures and types.
53+
### ModuleDataService Methods
54+
55+
| Method | Parameters | Returns | Description |
56+
|--------|------------|---------|-------------|
57+
| fetchDataItems | `moduleId: string`, `options?: FetchOptions` | `Promise<DataItem[]>` | Fetches data items for module |
58+
| createDataItem | `moduleId: string`, `data: DataItem` | `Promise<DataItem>` | Creates new data item |
59+
| updateDataItem | `moduleId: string`, `id: string`, `data: Partial<DataItem>` | `Promise<DataItem>` | Updates existing data item |
60+
| deleteDataItem | `moduleId: string`, `id: string` | `Promise<void>` | Deletes data item |
61+
62+
## Testing
63+
64+
Test coverage reports are generated in `coverage/` directory when running:
65+
66+
```bash
67+
pnpm test
68+
```
69+
70+
See individual test files in `tests/` directory for implementation details.
4471

4572
## Related Packages
4673

0 commit comments

Comments
 (0)