Skip to content

Commit 36fb4de

Browse files
Patrick-EhimenPatrick-Ehimen
authored
Merge pull request #18 from Patrick-Ehimen/feat/sdk-wrapper
 feat: implement foundational Lighthouse AI SDK wrapper
2 parents b132010 + 597949b commit 36fb4de

File tree

12 files changed

+1658
-22
lines changed

12 files changed

+1658
-22
lines changed

‎packages/sdk-wrapper/README.md‎

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
# @lighthouse-tooling/sdk-wrapper
2+
3+
Unified SDK wrapper that abstracts Lighthouse and Kavach SDK complexity for AI agents. This is a foundational component used by MCP servers and IDE extensions to interact with Lighthouse storage services.
4+
5+
## Features
6+
7+
- **Unified Interface**: Single SDK for all Lighthouse operations
8+
- **Authentication Management**: Automatic JWT token refresh
9+
- **Progress Tracking**: Real-time progress updates with event emission
10+
- **Error Handling**: Comprehensive error handling with retry logic
11+
- **TypeScript Support**: Full TypeScript definitions and documentation
12+
- **AI-Friendly**: Designed specifically for AI agent integration
13+
14+
## Installation
15+
16+
```bash
17+
npm install @lighthouse-tooling/sdk-wrapper
18+
```
19+
20+
## Quick Start
21+
22+
```typescript
23+
import { LighthouseAISDK } from "@lighthouse-tooling/sdk-wrapper";
24+
25+
// Initialize SDK
26+
const sdk = new LighthouseAISDK({
27+
apiKey: "your-lighthouse-api-key",
28+
baseUrl: "https://node.lighthouse.storage", // optional
29+
timeout: 30000, // optional
30+
maxRetries: 3, // optional
31+
debug: false, // optional
32+
});
33+
34+
// Initialize and authenticate
35+
await sdk.initialize();
36+
37+
// Upload a file
38+
const fileInfo = await sdk.uploadFile("./data/model.json", {
39+
fileName: "my-model.json",
40+
mimeType: "application/json",
41+
encrypt: false,
42+
onProgress: (progress) => {
43+
console.log(`Upload progress: ${progress.percentage}%`);
44+
},
45+
});
46+
47+
console.log("File uploaded:", fileInfo.hash);
48+
49+
// Download a file
50+
await sdk.downloadFile(fileInfo.hash, "./downloads/model.json", {
51+
onProgress: (progress) => {
52+
console.log(`Download progress: ${progress.percentage}%`);
53+
},
54+
});
55+
56+
// List uploaded files
57+
const files = await sdk.listFiles(10, 0);
58+
console.log("Uploaded files:", files.files);
59+
60+
// Cleanup
61+
sdk.destroy();
62+
```
63+
64+
## API Reference
65+
66+
### LighthouseAISDK
67+
68+
Main SDK class that provides unified access to Lighthouse functionality.
69+
70+
#### Constructor
71+
72+
```typescript
73+
new LighthouseAISDK(config: LighthouseConfig)
74+
```
75+
76+
#### Methods
77+
78+
##### `initialize(): Promise<void>`
79+
80+
Initialize the SDK and authenticate with Lighthouse.
81+
82+
##### `uploadFile(filePath: string, options?: UploadOptions): Promise<FileInfo>`
83+
84+
Upload a file to Lighthouse with progress tracking.
85+
86+
**Parameters:**
87+
88+
- `filePath`: Path to the file to upload
89+
- `options`: Upload configuration options
90+
91+
**Returns:** Promise resolving to file information
92+
93+
##### `downloadFile(cid: string, outputPath: string, options?: DownloadOptions): Promise<string>`
94+
95+
Download a file from Lighthouse.
96+
97+
**Parameters:**
98+
99+
- `cid`: IPFS CID of the file to download
100+
- `outputPath`: Local path to save the downloaded file
101+
- `options`: Download configuration options
102+
103+
**Returns:** Promise resolving to the output file path
104+
105+
##### `getFileInfo(cid: string): Promise<FileInfo>`
106+
107+
Get metadata and information about a file.
108+
109+
##### `listFiles(limit?: number, offset?: number): Promise<ListFilesResponse>`
110+
111+
List files uploaded by the authenticated user.
112+
113+
##### `getAuthState(): AuthState`
114+
115+
Get current authentication state.
116+
117+
##### `getActiveOperations(): string[]`
118+
119+
Get list of active operation IDs.
120+
121+
##### `getOperationProgress(operationId: string): ProgressInfo | null`
122+
123+
Get progress information for a specific operation.
124+
125+
##### `cancelOperation(operationId: string): void`
126+
127+
Cancel an ongoing operation.
128+
129+
##### `destroy(): void`
130+
131+
Cleanup resources and disconnect.
132+
133+
### Events
134+
135+
The SDK emits various events for progress tracking and status updates:
136+
137+
```typescript
138+
sdk.on("upload:start", (event) => console.log("Upload started"));
139+
sdk.on("upload:progress", (event) =>
140+
console.log("Upload progress:", event.data)
141+
);
142+
sdk.on("upload:complete", (event) => console.log("Upload completed"));
143+
sdk.on("upload:error", (event) => console.error("Upload failed:", event.error));
144+
145+
sdk.on("download:start", (event) => console.log("Download started"));
146+
sdk.on("download:progress", (event) =>
147+
console.log("Download progress:", event.data)
148+
);
149+
sdk.on("download:complete", (event) => console.log("Download completed"));
150+
sdk.on("download:error", (event) =>
151+
console.error("Download failed:", event.error)
152+
);
153+
154+
sdk.on("auth:refresh", () => console.log("Token refreshed"));
155+
sdk.on("auth:error", (error) => console.error("Auth error:", error));
156+
```
157+
158+
## Configuration
159+
160+
### LighthouseConfig
161+
162+
```typescript
163+
interface LighthouseConfig {
164+
/** API key for authentication */
165+
apiKey: string;
166+
/** Base URL for Lighthouse API (optional) */
167+
baseUrl?: string;
168+
/** Timeout for requests in milliseconds */
169+
timeout?: number;
170+
/** Maximum number of retry attempts */
171+
maxRetries?: number;
172+
/** Enable debug logging */
173+
debug?: boolean;
174+
}
175+
```
176+
177+
### UploadOptions
178+
179+
```typescript
180+
interface UploadOptions {
181+
/** File name override */
182+
fileName?: string;
183+
/** MIME type override */
184+
mimeType?: string;
185+
/** Progress callback function */
186+
onProgress?: (progress: ProgressInfo) => void;
187+
/** Enable encryption */
188+
encrypt?: boolean;
189+
/** Custom metadata */
190+
metadata?: Record<string, any>;
191+
}
192+
```
193+
194+
### DownloadOptions
195+
196+
```typescript
197+
interface DownloadOptions {
198+
/** Progress callback function */
199+
onProgress?: (progress: ProgressInfo) => void;
200+
/** Expected file size for progress calculation */
201+
expectedSize?: number;
202+
}
203+
```
204+
205+
## Error Handling
206+
207+
The SDK provides comprehensive error handling with automatic retry logic for transient failures:
208+
209+
```typescript
210+
try {
211+
const fileInfo = await sdk.uploadFile("./large-file.zip");
212+
console.log("Upload successful:", fileInfo.hash);
213+
} catch (error) {
214+
if (error.message.includes("network")) {
215+
console.log("Network error - will retry automatically");
216+
} else {
217+
console.error("Upload failed:", error.message);
218+
}
219+
}
220+
```
221+
222+
## Development
223+
224+
### Building
225+
226+
```bash
227+
npm run build
228+
```
229+
230+
### Testing
231+
232+
```bash
233+
npm test
234+
npm run test:watch
235+
npm run test:coverage
236+
```
237+
238+
### Linting
239+
240+
```bash
241+
npm run lint
242+
npm run lint:fix
243+
```
244+
245+
## Contributing
246+
247+
1. Fork the repository
248+
2. Create a feature branch
249+
3. Make your changes
250+
4. Add tests for new functionality
251+
5. Ensure all tests pass
252+
6. Submit a pull request
253+
254+
## License
255+
256+
MIT License - see LICENSE file for details.

‎packages/sdk-wrapper/jest.config.js‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
/** @type {import('jest').Config} */
2+
module.exports = {
3+
preset: "ts-jest",
4+
testEnvironment: "node",
5+
roots: ["<rootDir>/src"],
6+
testMatch: ["**/__tests__/**/*.ts", "**/?(*.)+(spec|test).ts"],
7+
transform: {
8+
"^.+\\.ts$": "ts-jest",
9+
},
10+
collectCoverageFrom: [
11+
"src/**/*.ts",
12+
"!src/**/*.d.ts",
13+
"!src/**/__tests__/**",
14+
"!src/**/*.test.ts",
15+
"!src/**/*.spec.ts",
16+
],
17+
coverageDirectory: "coverage",
18+
coverageReporters: ["text", "lcov", "html"],
19+
coverageThreshold: {
20+
global: {
21+
branches: 90,
22+
functions: 90,
23+
lines: 90,
24+
statements: 90,
25+
},
26+
},
27+
setupFilesAfterEnv: ["<rootDir>/src/__tests__/setup.ts"],
28+
testTimeout: 10000,
29+
};

‎packages/sdk-wrapper/package.json‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,36 @@
11
{
22
"name": "@lighthouse-tooling/sdk-wrapper",
33
"version": "0.1.0",
4+
"description": "Unified SDK wrapper for Lighthouse and Kavach SDK complexity abstraction",
45
"main": "dist/index.js",
56
"types": "dist/index.d.ts",
67
"scripts": {
78
"build": "tsc",
9+
"dev": "tsc --watch",
810
"test": "jest",
911
"test:watch": "jest --watch",
1012
"test:coverage": "jest --coverage",
1113
"lint": "eslint src/**/*.ts",
14+
"lint:fix": "eslint src/**/*.ts --fix",
15+
"format": "prettier --write .",
16+
"format:check": "prettier --check .",
1217
"clean": "rm -rf dist"
1318
},
1419
"dependencies": {
1520
"@lighthouse-tooling/types": "workspace:*",
1621
"@lighthouse-tooling/shared": "workspace:*",
17-
"@lighthouse-web3/sdk": "^0.2.3"
22+
"@lighthouse-web3/sdk": "^0.2.3",
23+
"eventemitter3": "^5.0.1",
24+
"axios": "^1.6.0"
1825
},
19-
"scripts": {
20-
"lint": "eslint .",
21-
"lint:fix": "eslint . --fix",
22-
"format": "prettier --write .",
23-
"format:check": "prettier --check ."
24-
}
26+
"devDependencies": {
27+
"@types/jest": "^29.5.0",
28+
"@types/node": "^20.0.0",
29+
"jest": "^29.5.0",
30+
"ts-jest": "^29.1.0",
31+
"typescript": "^5.0.0"
32+
},
33+
"files": [
34+
"dist/**/*"
35+
]
2536
}

0 commit comments

Comments
 (0)