@package-uploader/core 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,303 @@
+# @package-uploader/core
+
+Upload Rise course packages to LMS platforms with optional auto-patching via @patch-adams/core.
+
+## Features
+
+- **Course upload**: Upload SCORM, cmi5, xAPI packages to LMS
+- **Version management**: Upload new versions to existing documents
+- **Auto-patching**: Optionally patch courses before upload (requires @patch-adams/core)
+- **Folder/document browsing**: List folders, documents, and shared links
+- **Async upload support**: Handle large files with async processing
+
+## Installation
+
+```bash
+npm install @package-uploader/core
+
+# Optional: Enable auto-patching
+npm install @patch-adams/core
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Initialize config file
+npx package-upload init
+
+# Upload a course to a folder
+npx package-upload upload course.zip --folder 12345
+
+# Upload a new version to existing document
+npx package-upload update course.zip --document-id 67890
+
+# Check async upload status
+npx package-upload status <jobId>
+```
+
+### Programmatic Usage
+
+```typescript
+import { PackageUploaderClient } from '@package-uploader/core';
+
+const client = new PackageUploaderClient({
+  baseUrl: 'https://your-lms.example.com',
+  apiKey: 'your-api-key',
+
+  // Optional: Enable auto-patching
+  patchAdams: {
+    enabled: true,
+    remoteDomain: 'https://cdn.example.com/rise-overrides',
+  },
+});
+
+// Upload a new course
+const result = await client.uploadCourse(fileBuffer, 'course.zip', {
+  folderId: '12345',
+  title: 'My Course',
+  description: 'Course description',
+});
+
+console.log('Document ID:', result.documentId);
+
+// Upload a new version
+const versionResult = await client.uploadVersion(fileBuffer, 'course.zip', {
+  documentId: '67890',
+  note: 'Updated content',
+});
+```
+
+## Configuration
+
+### Config File
+
+Create `uploader.config.json`:
+
+```json
+{
+  "baseUrl": "https://your-lms.example.com",
+  "apiKey": "your-api-key",
+  "timeout": 30000,
+  "patchAdams": {
+    "enabled": true,
+    "remoteDomain": "https://cdn.example.com/rise-overrides"
+  }
+}
+```
+
+### Environment Variables
+
+```bash
+UPLOADER_BASE_URL=https://your-lms.example.com
+UPLOADER_API_KEY=your-api-key
+UPLOADER_TIMEOUT=30000
+PATCH_ADAMS_DOMAIN=https://cdn.example.com/rise-overrides
+```
+
+## API Reference
+
+### `PackageUploaderClient`
+
+```typescript
+class PackageUploaderClient {
+  constructor(config: UploaderConfig)
+
+  // Upload Methods
+  uploadCourse(buffer: Buffer, filename: string, options: UploadOptions): Promise<CourseUploadResult>
+  uploadVersion(buffer: Buffer, filename: string, options: VersionUploadOptions): Promise<CourseUploadResult>
+  getUploadStatus(jobId: string): Promise<JobStatus>
+  waitForUpload(jobId: string, options?: WaitOptions): Promise<CourseUploadResult>
+
+  // Folder Methods
+  listFolders(options?: FolderListOptions): Promise<Folder[]>
+  getFolder(folderId: string | number): Promise<Folder>
+  listSubfolders(folderId: string | number, options?: FolderListOptions): Promise<Folder[]>
+
+  // Document Methods
+  listDocuments(options?: DocumentListOptions): Promise<Document[]>
+  listFolderDocuments(folderId: string | number, options?: DocumentListOptions): Promise<Document[]>
+  getDocument(documentId: string | number): Promise<Document>
+  getDocumentVersions(documentId: string | number): Promise<DocumentVersion[]>
+
+  // Shared Link Methods
+  listSharedLinks(documentId: string | number): Promise<SharedLink[]>
+  createSharedLink(documentId: string | number, options: CreateSharedLinkOptions): Promise<SharedLink>
+  getOrCreateLaunchLink(documentId: string | number): Promise<string>
+}
+```
+
+### Types
+
+```typescript
+interface UploaderConfig {
+  baseUrl: string;
+  apiKey: string;
+  timeout?: number;           // default: 30000
+  patchAdams?: {
+    enabled: boolean;
+    remoteDomain: string;
+  };
+}
+
+interface UploadOptions {
+  folderId: string;
+  externalId?: string;        // For upsert behavior
+  title?: string;
+  description?: string;
+  author?: string;
+  language?: string;
+  note?: string;
+  async?: boolean;            // Use async upload
+  skipPatch?: boolean;        // Skip auto-patching
+}
+
+interface VersionUploadOptions {
+  documentId: string;
+  note?: string;
+  description?: string;
+  author?: string;
+  async?: boolean;
+  skipPatch?: boolean;
+}
+
+interface CourseUploadResult {
+  success: boolean;
+  documentId: number | null;
+  versionId: number | null;
+  documentName: string;
+  folderId: number;
+  updated: boolean;
+  warnings: string[];
+  errors: string[];
+  jobId?: string;             // For async uploads
+}
+```
+
+## CLI Commands
+
+```bash
+# Upload a course
+package-upload upload <file> [options]
+
+Options:
+  -f, --folder <id>         Target folder ID (required)
+  -e, --external-id <id>    External ID for upsert
+  -t, --title <title>       Document title
+  -d, --description <desc>  Document description
+  -a, --author <author>     Document author
+  -n, --note <note>         Version note
+  --async                   Upload asynchronously
+  --skip-patch              Skip auto-patching
+  --wait                    Wait for async upload
+
+# Upload new version
+package-upload update <file> [options]
+
+Options:
+  -i, --document-id <id>    Target document ID (required)
+  -n, --note <note>         Version note
+  --async                   Upload asynchronously
+  --skip-patch              Skip auto-patching
+  --wait                    Wait for async upload
+
+# Check upload status
+package-upload status <jobId>
+
+# Initialize config
+package-upload init
+```
+
+## Auto-Patching with @patch-adams/core
+
+When `patchAdams.enabled` is true and `@patch-adams/core` is installed, courses are automatically patched before upload:
+
+```typescript
+const client = new PackageUploaderClient({
+  baseUrl: 'https://your-lms.example.com',
+  apiKey: 'your-api-key',
+  patchAdams: {
+    enabled: true,
+    remoteDomain: 'https://cdn.example.com/rise-overrides',
+  },
+});
+
+// This course will be patched before upload
+await client.uploadCourse(buffer, 'course.zip', {
+  folderId: '12345',
+});
+
+// Skip patching for this upload
+await client.uploadCourse(buffer, 'course.zip', {
+  folderId: '12345',
+  skipPatch: true,
+});
+```
+
+## Examples
+
+### List All Folders
+
+```typescript
+const folders = await client.listFolders();
+folders.forEach(f => console.log(f.id, f.name));
+```
+
+### Browse Documents in Folder
+
+```typescript
+const docs = await client.listFolderDocuments('12345', {
+  filterText: 'training',
+  includeSharedLinks: true,
+});
+```
+
+### Get Launch URL for Course
+
+```typescript
+const launchUrl = await client.getOrCreateLaunchLink('67890');
+console.log('Launch at:', launchUrl);
+```
+
+### Async Upload with Polling
+
+```typescript
+const result = await client.uploadCourse(buffer, 'large-course.zip', {
+  folderId: '12345',
+  async: true,
+});
+
+if (result.jobId) {
+  const finalResult = await client.waitForUpload(result.jobId, {
+    pollInterval: 2000,
+    maxWait: 300000,
+  });
+  console.log('Upload complete:', finalResult.documentId);
+}
+```
+
+## Server Integration
+
+For Express/Node.js server integration, see `@package-uploader/ui` which includes a ready-to-deploy server.
+
+```typescript
+import express from 'express';
+import { PackageUploaderClient } from '@package-uploader/core';
+
+const app = express();
+const client = new PackageUploaderClient({ /* config */ });
+
+app.post('/api/upload', async (req, res) => {
+  const result = await client.uploadCourse(
+    req.file.buffer,
+    req.file.originalname,
+    { folderId: req.body.folderId }
+  );
+  res.json(result);
+});
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@package-uploader/core",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Patch and upload Rise courses to LMS platforms",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",