{"id":28947929,"url":"https://github.com/anistark/lumox","last_synced_at":"2026-04-29T22:34:22.993Z","repository":{"id":294314164,"uuid":"986584485","full_name":"anistark/lumox","owner":"anistark","description":"A TypeScript SDK for local-first encrypted storage.","archived":false,"fork":false,"pushed_at":"2025-05-20T13:12:13.000Z","size":170,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-04T10:28:07.590Z","etag":null,"topics":["decentralised-library","ipfs","javascript","nodejs","sdk","sdk-typescript","storage","typescript-library"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/lumox","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anistark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-19T20:38:13.000Z","updated_at":"2025-05-20T13:12:17.000Z","dependencies_parsed_at":"2025-05-19T21:52:01.161Z","dependency_job_id":null,"html_url":"https://github.com/anistark/lumox","commit_stats":null,"previous_names":["anistark/lumox"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/anistark/lumox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anistark%2Flumox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anistark%2Flumox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anistark%2Flumox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anistark%2Flumox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anistark","download_url":"https://codeload.github.com/anistark/lumox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anistark%2Flumox/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269962062,"owners_count":24504263,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-11T02:00:10.019Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["decentralised-library","ipfs","javascript","nodejs","sdk","sdk-typescript","storage","typescript-library"],"created_at":"2025-06-23T10:02:32.284Z","updated_at":"2025-11-11T11:22:08.544Z","avatar_url":"https://github.com/anistark.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lumox\n\nA TypeScript SDK for local-first encrypted storage with optional IPFS backup capabilities.\n\n[![npm version](https://img.shields.io/npm/v/lumox.svg)](https://www.npmjs.com/package/lumox) ![NPM Downloads](https://img.shields.io/npm/dm/lumox) ![npm bundle size](https://img.shields.io/bundlephobia/min/lumox) \n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- **Local-First Storage**: Encrypted chat data stored locally using SQLite compiled to WebAssembly\n- **Strong Encryption**: End-to-end encryption using the WebCrypto API\n- **Cross-Platform**: Works in browsers, Node.js, and React Native\n- **Modular Design**: Easily integrate specific components or use the full SDK\n- **Comprehensive Error Handling**: Detailed error codes and messages for effective debugging\n- **Configurable Logging**: Flexible logging system that adapts to your application needs\n\n## Installation\n\n```bash\n# Using npm\nnpm install lumox\n\n# Using yarn\nyarn add lumox\n\n# Using pnpm\npnpm add lumox\n```\n\n## Quick Start\n\n```ts\nimport { LumoxClient, SqliteStorageProvider, WebCryptoProvider } from 'lumox';\nimport initSqlJs from 'sql.js';\n\nasync function main() {\n  // Initialize SQL.js\n  const SQL = await initSqlJs();\n  \n  // Create storage and crypto providers\n  const storage = new SqliteStorageProvider({ sqlInstance: SQL });\n  const crypto = new WebCryptoProvider();\n  \n  // Initialize Lumox client\n  const lumox = new LumoxClient({ storage, crypto });\n  await lumox.initialize();\n  \n  // Generate encryption key\n  await lumox.generateEncryptionKey();\n  \n  // Send an encrypted message\n  const messageId = await lumox.sendMessage('alice', 'bob', 'Hello, encrypted world!');\n  console.log(`Message sent with ID: ${messageId}`);\n  \n  // Retrieve and decrypt messages\n  const messages = await lumox.getMessages('alice', 'bob');\n  console.log('Messages:', messages);\n  \n  // Export database for backup\n  const dbExport = await lumox.exportData();\n  console.log(`Exported ${dbExport.byteLength} bytes of data`);\n  \n  // Clean up\n  await lumox.close();\n}\n\nmain().catch(console.error);\n```\n\n## API Reference\n\n### LumoxClient\n\nThe main client for interacting with the Lumox system.\n\n```ts\nconst lumox = new LumoxClient({\n  storage: storageProvider,\n  crypto: cryptoProvider,\n  logger: loggerInstance // Optional\n});\n```\n\n#### Methods\n\n- **initialize()**: Initialize the client components\n- **generateEncryptionKey()**: Create a new encryption key\n- **exportEncryptionKey()**: Export the current encryption key as a string\n- **importEncryptionKey(keyData)**: Import an encryption key\n- **sendMessage(senderId, receiverId, content, metadata?)**: Send an encrypted message\n- **getMessages(user1Id, user2Id, limit?, offset?)**: Retrieve and decrypt messages\n- **exportData()**: Export the database as a Uint8Array\n- **importData(data, overwrite?)**: Import database data\n- **close()**: Clean up resources\n\n### StorageProvider\n\nInterface for storage implementations.\n\n```ts\n// Default SQLite implementation\nconst storage = new SqliteStorageProvider({\n  sqlInstance: SQL,\n  // Optional: filename for persistent storage in browsers\n  filename: '/sql/chat.db',\n  // Optional: initial data to load\n  initialData: existingDbData,\n  // Optional: logger instance\n  logger: loggerInstance\n});\n```\n\n### CryptoProvider\n\nInterface for encryption implementations.\n\n```ts\n// Default WebCrypto implementation\nconst crypto = new WebCryptoProvider({\n  // Optional: logger instance\n  logger: loggerInstance\n});\n```\n\n## Error Handling and Logging\n\nLumox provides a comprehensive error handling and logging system. See [Error Handling and Logging](./ERROR_HANDLING.md) for details.\n\n## Advanced Usage\n\n### Persistence in Browser\n\nFor persistent storage in browsers, you can use the optional `absurd-sql` integration:\n\n```ts\nimport { SQLiteFS } from 'absurd-sql';\nimport IndexedDBBackend from 'absurd-sql/dist/indexeddb-backend';\n\n// Set up absurd-sql for persistence\nconst sqlFS = new SQLiteFS(SQL.FS, new IndexedDBBackend());\nSQL.register_for_idb(sqlFS);\nSQL.FS.mkdir('/sql');\nSQL.FS.mount(sqlFS, {}, '/sql');\n\n// Create storage with persistence\nconst storage = new SqliteStorageProvider({\n  sqlInstance: SQL,\n  filename: '/sql/chat.db'\n});\n```\n\n### Importing and Exporting\n\nExport and import database for backup or migration:\n\n```ts\n// Export database\nconst dbData = await lumox.exportData();\n\n// Save to a file in Node.js\nawait fs.promises.writeFile('backup.sqlite', Buffer.from(dbData));\n\n// Later, import the database\nconst importData = await fs.promises.readFile('backup.sqlite');\nawait lumox.importData(new Uint8Array(importData.buffer), true);\n```\n\n## Roadmap\n\n### v1.0 (Current)\n- Local storage using SQLite-WASM\n- End-to-end encryption with WebCrypto\n- Comprehensive error handling and logging\n\n### v1.5 (Planned)\n- Identity integration for key derivation\n- Support for Web3 wallets (Ethereum, Solana)\n- DID integration\n\n### v2.0 (Future)\n- IPFS backup capabilities\n- Conflict resolution for multi-device sync\n- Enhanced privacy features\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build the project\npnpm build\n\n# Run tests\npnpm test\n\n# Run example\npnpm example\n\n# Run error handling example\npnpm example:errors\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the [MIT License](./License).\n\n## Acknowledgments\n\n- SQL.js for SQLite compilation to WebAssembly\n- The WebCrypto API team for browser encryption capabilities\n- IPFS project for decentralized storage concepts\n\n---\n\nBuilt with ❤️ for secure, local-first communications.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanistark%2Flumox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanistark%2Flumox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanistark%2Flumox/lists"}