@pelygo/janus 0.1.1

package/README.md

@@ -0,0 +1,264 @@
+# @pelygo/janus
+
+TypeScript API client for JANUS (VCOMSUITE backend) endpoints with full type safety.
+
+## Installation
+
+```bash
+npm install @pelygo/janus @pelygo/auth
+```
+
+## Quick Start
+
+```typescript
+import { createJanusApi } from '@pelygo/janus';
+
+// Create API instance
+const janus = createJanusApi({
+  baseUrl: 'https://api.janus.pelygo.com',
+  onUnauthorized: () => {
+    // Handle session expiry (redirect to login, etc.)
+  },
+});
+
+// Authenticate
+await janus.auth.login('username', 'password');
+
+// Use typed resources
+const clients = await janus.clients.getAll();
+const returns = await janus.returns.query({ clientId: 5, pageSize: 50 });
+```
+
+## API Reference
+
+### Creating the Client
+
+```typescript
+const janus = createJanusApi({
+  baseUrl: string;           // JANUS API base URL
+  onUnauthorized?: () => void;  // Called on 401 responses
+});
+```
+
+### Authentication
+
+The client wraps `@pelygo/auth` for authentication:
+
+```typescript
+// Login
+await janus.auth.login(username, password);
+
+// Get current user
+const user = await janus.auth.getUser();
+
+// Logout
+await janus.auth.logout();
+
+// Check if authenticated
+const isLoggedIn = janus.auth.isAuthenticated();
+```
+
+### Clients Resource
+
+```typescript
+// Get all clients
+const clients = await janus.clients.getAll();
+
+// Get single client
+const client = await janus.clients.getById(5);
+
+// Update client
+const updated = await janus.clients.update(5, { name: 'New Name' });
+
+// Get courier services for client
+const services = await janus.clients.getCourierServices(5);
+const service = await janus.clients.getCourierServiceById(5, serviceId);
+await janus.clients.updateCourierService(5, serviceId, { active: true });
+```
+
+### Returns Resource
+
+```typescript
+// Query returns with filters
+const returns = await janus.returns.query({
+  clientId: 5,
+  last_status_ids: '1,2,3',
+  created_at: '2024-01-01',
+  created_to: '2024-12-31',
+  pageSize: 100,
+});
+
+// Get single return with items
+const ret = await janus.returns.getById(123, { includeAssociations: true });
+
+// Create a return
+const newReturn = await janus.returns.create({
+  client_id: 5,
+  customer_name: 'John Doe',
+  // ...
+});
+
+// Update a return
+await janus.returns.update(123, { customer_name: 'Jane Doe' });
+
+// Delete a return
+await janus.returns.delete(123);
+
+// Manage statuses
+await janus.returns.addStatus(123, statusId);
+await janus.returns.removeStatus(123, statusId);
+const statuses = await janus.returns.getStatuses(123);
+
+// Manage comments
+await janus.returns.addComment(123, 'Comment text');
+await janus.returns.removeComment(123, commentId);
+const comments = await janus.returns.getComments(123);
+
+// Manage items
+const items = await janus.returns.getItems(123);
+await janus.returns.addItem(123, { wms_product_sku: 'SKU123', qty: 2 });
+await janus.returns.updateItem(123, itemId, { qty: 3 });
+
+// Approval workflow
+await janus.returns.setApproval(123, true);  // Approve
+await janus.returns.setApproval(123, false); // Reject
+
+// Reference data
+const reasons = await janus.returns.getReasons();
+const allStatuses = await janus.returns.getAllStatuses();
+const filterOptions = await janus.returns.getFilterOptions(5);
+```
+
+### Reports Resource
+
+```typescript
+// Returns summary report
+const summary = await janus.reports.returnsSummary({
+  clientId: 5,
+  created_at: '2024-01-01',
+  created_to: '2024-12-31',
+  groupBy: 'month',
+});
+
+// CSV export
+const csvData = await janus.reports.returnsSummaryCsv({ clientId: 5 });
+
+// Returns by reason
+const reasonReport = await janus.reports.returnsReasons({ clientId: 5 });
+const reasonCsv = await janus.reports.returnsReasonsCsv({ clientId: 5 });
+
+// Returns overview
+const overview = await janus.reports.returnsOverview({ clientId: 5 });
+const overviewCsv = await janus.reports.returnsOverviewCsv({ clientId: 5 });
+
+// Statistics
+const stats = await janus.reports.returnsStats(5);
+```
+
+### Helpers Resource (Public Endpoints)
+
+```typescript
+// Submit return portal form (no auth required)
+const result = await janus.helpers.submitReturnPortalForm(formData);
+
+// Get notification settings
+const settings = await janus.helpers.getNotificationSettings(clientId);
+```
+
+## Types
+
+All entity types are exported and can be imported:
+
+```typescript
+import type {
+  Client,
+  Return,
+  ReturnItem,
+  ReturnStatus,
+  ReturnReason,
+  User,
+  // ... more types
+} from '@pelygo/janus';
+```
+
+### Filter Types
+
+```typescript
+import type { ReturnsQueryParams, ReportFilters } from '@pelygo/janus';
+
+const filters: ReturnsQueryParams = {
+  clientId: 5,
+  last_status_ids: '1,2',
+  pageSize: 50,
+};
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm run test
+
+# Run tests once
+npm run test:run
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+
+# Generate entity types from v2 TypeORM entities
+npm run generate-types
+```
+
+### Integration Tests
+
+To run integration tests against a real JANUS API, set environment variables:
+
+```bash
+export JANUS_API_URL="https://api.janus.dev.pelygo.com"
+export JANUS_TEST_USERNAME="testuser"
+export JANUS_TEST_PASSWORD="testpass"
+export JANUS_TEST_CLIENT_ID="5"
+
+npm run test:integration
+```
+
+## Architecture
+
+```
+src/
+├── index.ts           # Main exports
+├── client.ts          # createJanusApi() factory
+├── types/
+│   ├── entities/      # Generated entity interfaces
+│   ├── filters.ts     # Query filter types
+│   └── responses.ts   # API response types
+├── resources/
+│   ├── clients.ts     # Clients API
+│   ├── returns.ts     # Returns API
+│   ├── reports.ts     # Reports API
+│   └── helpers.ts     # Public endpoints
+└── utils/
+    └── query-builder.ts  # URL query string builder
+```
+
+## Base44 Integration
+
+For Base44 applications, see the **[Base44 Integration Guide](docs/BASE44_GUIDE.md)** which includes:
+
+- Installation and setup for Base44
+- AI prompt examples for generating pages
+- Common patterns and code snippets
+
+## Related Packages
+
+- [@pelygo/auth](https://www.npmjs.com/package/@pelygo/auth) - Authentication client (peer dependency)
+
+## License
+
+See LICENSE file.