cybertipline-tools 0.1.0 → 0.2.0

package/README.md

@@ -5,50 +5,132 @@ A **unofficial** collection of tools for interacting with the National Center fo
 ## Installation
 
 ```bash
-pnpm install cybertipline-tools
+# Using pnpm
+pnpm add cybertipline-tools
+
+# Using npm
+npm install cybertipline-tools
+
+# Using yarn
+yarn add cybertipline-tools
 ```
 
-## Requirements
+## Quick Start
+
+```typescript
+import { Client, Environment, IncidentType } from 'cybertipline-tools';
+
+// Create a new client
+const client = new Client({
+  environment: Environment.Testing, // Use Testing for development
+  credentials: {
+    username: 'your-username',
+    password: 'your-password',
+  },
+});
+
+// Test your connection
+const status = await client.getStatus();
+console.log('Connected:', status.data.responseDescription);
+
+// Submit a report
+const report = await client.submitReport({
+  incidentSummary: {
+    incidentType: IncidentType.ChildSexTourism,
+    // ... other required fields
+  },
+  reporter: {
+    reportingPerson: {
+      email: 'reporter@example.com',
+      // ... other required fields
+    },
+  },
+});
+console.log('Report ID:', report.data.reportId);
+
+// Upload a file
+const fileUpload = await client.uploadFile({
+  id: report.data.reportId,
+  file: new File(['...'], 'evidence.jpg'),
+});
+console.log('File ID:', fileUpload.data.fileId);
+
+// Add file details
+await client.submitFileDetails({
+  reportId: Number(report.data.reportId),
+  fileId: fileUpload.data.fileId,
+  fileName: 'evidence.jpg',
+  // ... other optional fields
+});
+
+// Mark report as complete
+await client.finishReport({
+  id: report.data.reportId,
+});
+```
 
-We officially support Node.js 22.x and later, but the library may work on older versions.
+## Requirements
 
-The package exports ESM modules, so you may need to do some extra configuration to use it in a CommonJS environment.
+- Node.js 24.x or later (TypeScript 5.x for type definitions)
+  - Older versions may work, but are not officially verified.
+- ESM module support
+  - CommonJS is exported, but not officially tested. We welcome contributions to improve this.
 
 ## Features
 
-- TypeScript support
-  - We export TypeScript declaration files with the package for all documented APIs.
-- Inline documentation
-  - We document all our APIs and types with JSDoc comments to give you inline documentation in your editor.
-- Standalone utils
-  - Don't need the API client? Just import the utils you need.
-
-Coming soon™️:
-- [ ] API client, ability to call the CyberTipline APIs.
-  - [ ] JSON to XML builder. Convert input JSON objects to XML for post calls.
-  - [ ] XML to JSON conversion for responses from the API.
-  - APIs to support:
-    - [ ] GET /status
-    - [ ] POST /submit
-    - [ ] POST /upload
-    - [ ] POST /fileinfo
-    - [ ] POST /finish
-    - [ ] POST /retract 
-- [ ] Support batch reporting.
-  - [ ] Generate a full report and batch send.
-- [ ] Strict schema validation (Zod, or similar).
-- [ ] Full test coverage.
-
-
-Maybe in the future:
-- [ ] E2E Validation against the CyberTipline API test endpoint.
-- [ ] Automatically generate TypeScript types from the CyberTipline xsd schema.
+✨ **Type Safety**
+- Full TypeScript support with detailed type definitions
+- Inline documentation with JSDoc comments
+  - Allowing for IDE autocompletion for all APIs
+
+🐛 **Error Handling**
+- Request ID extraction for all operations
+- Error handling with detailed messages
+
+🛠️ **API Support**
+- `GET /status` - Test API connectivity
+- `POST /submit` - Submit new reports
+- `POST /upload` - Upload evidence files
+- `POST /fileinfo` - Add file metadata
+- `POST /finish` - Complete reports
+- `POST /retract` - Cancel reports
+
+- You provide JSON, we convert it to XML and back, so no need to worry about XML!
+
+## Error Handling
+
+The client includes built-in error handling:
+
+```typescript
+try {
+  await client.getStatus();
+} catch (error) {
+  // All API errors include the Request-ID for troubleshooting
+  console.error('API Error:', error.message);
+  // Example: "Authentication failed (Request-ID: abc-123)"
+}
+```
+
+## Development Status
+
+🚧 **Todo**
+- [ ] Schema validation (Zod?)
+- [ ] Examples and demos
+- [ ] Documentation improvements
+- [ ] Performance optimizations
+- [ ] Stabilize developer experience
+
+🔮 **Possible Future Plans**
+- [ ] E2E testing against running CyberTipline test environment
+- [ ] Batch reporting support
+- [ ] XSD schema to TypeScript generation
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT License - see the [LICENSE](LICENSE) file for details.
 
-## Links
+## Resources
 
-- Official API documentation: [CyberTipline Reporting API](https://report.cybertip.org/ispws/documentation)
-- Apply for access to [NCMEC CyberTipline](https://esp.ncmec.org/registration)
+- [CyberTipline API Documentation](https://report.cybertip.org/ispws/documentation) (official documentation from NCMEC)
+- [Apply for API Access](https://esp.ncmec.org/registration) (done by the NCMEC team)
+- [Report Issues](https://github.com/Johannes-Andersen/cybertipline-tools/issues)