@qaecy/cue-sdk 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
 # @qaecy/cue-sdk
 
-Headless JavaScript SDK for building apps on the QAECY platform. A framework-agnostic client that handles authentication and API access — the programmatic counterpart to the `@qaecy/cue-widget`.
+Headless JavaScript SDK for building apps on the QAECY Cue platform. A framework-agnostic client that handles authentication, project management, and API access — the programmatic counterpart to the `@qaecy/cue-widget`.
 
 ## Installation
 
@@ -33,10 +33,13 @@ await cue.auth.signIn('microsoft');
 // or
 await cue.auth.signIn('password', { email: 'user@example.com', password: 'secret' });
 
+// List projects
+const projects = await cue.api.projects.listProjects();
+
 // Search documents
 const results = await cue.api.search({
   term: 'What are the fire safety requirements?',
-  projectId: 'my-project-id',
+  projectId: projects[0].id,
 });
 
 console.log(results.response);
@@ -53,8 +56,8 @@ await cue.auth.signOut();
 | `apiKey` | `string` | ✅ | Firebase API key |
 | `appId` | `string` | ✅ | Firebase App ID |
 | `measurementId` | `string` | ✅ | Firebase Measurement ID |
-| `gatewayUrl` | `string` | — | Override the default API gateway URL |
-| `useEmulator` | `boolean` | — | Connect to local emulators (default: `false`) |
+| `environment` | `'production' \| 'emulator'` | — | Target environment (default: `'production'`) |
+| `endpoints` | `Partial<CueEndpoints>` | — | Override individual endpoint URLs (takes precedence over `environment`) |
 
 ## Auth
 
@@ -78,6 +81,14 @@ const user = await cue.auth.signIn('password', {
 });
 ```
 
+### `cue.auth.signInWithApiKey(cueApiKey, projectId)`
+
+Sign in using a Cue API key. Intended for non-interactive/server-side use (e.g. via `CueNode`):
+
+```typescript
+const user = await cue.auth.signInWithApiKey('MY_CUE_API_KEY', 'my-project-id');
+```
+
 ### `cue.auth.signOut()`
 
 ```typescript
@@ -139,6 +150,88 @@ const data = await cue.api.sparql(
 );
 ```
 
+## Projects
+
+Manage Cue projects via `cue.api.projects` (`CueProjects`).
+
+### `cue.api.projects.listProjects()`
+
+List all projects where the authenticated user is a member, syncer, or admin:
+
+```typescript
+const projects = await cue.api.projects.listProjects();
+projects.forEach((p) => console.log(p.id, p.name));
+```
+
+### `cue.api.projects.getProject(projectId)`
+
+Fetch a single project by ID. Returns `null` if not found:
+
+```typescript
+const project = await cue.api.projects.getProject('my-project-id');
+```
+
+### `cue.api.projects.createProject(options)`
+
+Create a new project. The authenticated user is automatically set as admin, syncer, and member:
+
+```typescript
+const project = await cue.api.projects.createProject({
+  name: 'My Project',
+  organizationID: 'my-org-id',
+  id: 'optional-custom-id', // defaults to a new UUID
+});
+```
+
+## Node.js — file sync
+
+For server-side or CLI use with file-sync capabilities, import from `@qaecy/cue-sdk/node`:
+
+```typescript
+import { CueNode } from '@qaecy/cue-sdk/node';
+
+const cue = new CueNode({
+  apiKey: 'YOUR_FIREBASE_API_KEY',
+  appId: 'YOUR_FIREBASE_APP_ID',
+  measurementId: 'YOUR_MEASUREMENT_ID',
+});
+
+// Use an API key for non-interactive sign-in
+await cue.auth.signInWithApiKey('MY_CUE_API_KEY', 'my-project-id');
+
+// Sync local files into a project
+const result = await cue.api.sync.sync(localFiles, {
+  spaceId: 'my-project-id',
+  providerId: 'my-provider',
+  userId: cue.auth.currentUser!.uid,
+  verbose: true,
+});
+
+console.log(`Synced ${result.syncCount} files (${result.failedUploads} failed)`);
+```
+
+### `cue.api.sync.sync(localFiles, options)`
+
+Compares local files against the remote project and uploads any that are missing or changed.
+
+| Option | Type | Description |
+|---|---|---|
+| `spaceId` | `string` | Project ID to sync into |
+| `providerId` | `string` | Identifier for the file source (e.g. `'local'`) |
+| `userId` | `string` | Authenticated user ID |
+| `verbose` | `boolean` | Enable progress logging (default: `false`) |
+
+Returns a `SyncResult`:
+
+| Field | Type | Description |
+|---|---|---|
+| `syncCount` | `number` | Files successfully synced |
+| `syncSize` | `number` | Bytes synced |
+| `failedUploads` | `number` | Files that failed to upload |
+| `totalCount` | `number` | Total file count (local + remote) |
+| `totalSize` | `number` | Total size across all files |
+| `rdfWritten` | `boolean` | Whether any RDF metadata was written |
+
 ## Advanced
 
 Access the raw Firebase `Auth` instance for advanced use cases: