@trainly/react 1.4.0 → 1.4.1

package/README.md

@@ -86,9 +86,58 @@ function MyComponent() {
 - ✅ **Zero Migration**: Works with your existing OAuth setup
 - ✅ **Simple Integration**: Just add `appId` and use `connectWithOAuthToken()`
 
-## 📁 **NEW: File Management**
+## 🏷️ **NEW: Custom Scopes (Zero Config)**
 
-Now users can manage their uploaded files directly:
+Tag your documents with custom attributes for powerful filtering and organization:
+
+```tsx
+import { useTrainly } from "@trainly/react";
+
+function MyApp() {
+  const { upload, ask } = useTrainly();
+
+  // 1. Upload with scopes - use any keys you want!
+  await upload(file, {
+    playlist_id: "xyz123",
+    workspace_id: "acme_corp",
+    project: "alpha",
+  });
+
+  // 2. Query with scope filters - only get results from matching documents
+  const answer = await ask("What are the key features?", {
+    scope_filters: { playlist_id: "xyz123" },
+  });
+  // ☝️ Only searches documents with playlist_id="xyz123"
+
+  // Query with multiple filters
+  const answer2 = await ask("Show me updates", {
+    scope_filters: {
+      workspace_id: "acme_corp",
+      project: "alpha",
+    },
+  });
+  // ☝️ Only searches documents matching ALL specified scopes
+
+  // Query everything (no filters)
+  const answer3 = await ask("What do I have?");
+  // ☝️ Searches ALL user's documents
+}
+```
+
+**No setup required!** Just pass any key-value pairs - perfect for multi-tenant apps, playlist systems, workspace organization, and more.
+
+**Use Cases:**
+
+- 🎵 **Playlist Apps**: Filter by `playlist_id` to query specific playlists
+- 🏢 **Multi-Tenant SaaS**: Filter by `tenant_id` or `workspace_id`
+- 📁 **Project Management**: Filter by `project_id` or `team_id`
+- 👥 **User Segmentation**: Filter by `user_tier`, `department`, etc.
+
+[📖 Full Scopes Guide](./SCOPES_GUIDE.md)
+
+## 📁 **File Management**
+
+Users can manage their uploaded files directly:
 
 ```tsx
 import { useTrainly, TrainlyFileManager } from "@trainly/react";
@@ -142,6 +191,67 @@ function MyApp() {
 - 📋 **List Files**: View all uploaded documents with metadata
 - 🗑️ **Delete Files**: Remove files and free up storage space
 - 📊 **Storage Analytics**: Track file sizes and storage usage
+
+## 🏷️ **NEW in v1.4.0: Custom Scopes**
+
+Tag your documents with custom attributes for powerful data segmentation!
+
+```tsx
+import { useTrainly } from "@trainly/react";
+
+function PlaylistUploader({ playlistId }) {
+  const { upload } = useTrainly();
+
+  const handleUpload = async (file: File) => {
+    // Upload with custom scope values
+    await upload(file, {
+      playlist_id: playlistId,
+      user_id: currentUser.id,
+      is_public: false,
+    });
+  };
+
+  return (
+    <input type="file" onChange={(e) => handleUpload(e.target.files[0])} />
+  );
+}
+```
+
+### Scope Features
+
+- 🎯 **Data Segmentation**: Keep playlists, workspaces, or projects separate
+- ⚡ **Faster Queries**: Filter at database level before vector search
+- 🔒 **Complete Isolation**: Multi-tenant apps with full data privacy
+- 🎨 **Flexible**: Define any custom attributes you need
+
+### With TrainlyUpload Component
+
+```tsx
+<TrainlyUpload
+  variant="drag-drop"
+  scopeValues={{
+    playlist_id: "playlist_123",
+    workspace_id: "workspace_456",
+  }}
+  onUpload={(files) => console.log("Uploaded with scopes!")}
+/>
+```
+
+### Complete Documentation
+
+See **[SCOPES_GUIDE.md](./SCOPES_GUIDE.md)** for:
+
+- Complete API reference
+- Real-world examples
+- Advanced patterns
+- Testing & debugging
+- Migration guide
+
+**Quick Reference:**
+
+- `upload(file, scopeValues)` - Upload with scopes
+- `bulkUploadFiles(files, scopeValues)` - Bulk upload with scopes
+- `<TrainlyUpload scopeValues={{...}} />` - Component with scopes
 - 🔄 **Auto-Refresh**: File list updates after uploads/deletions
 - 🎨 **Pre-built UI**: `TrainlyFileManager` component with styling
 - 🔒 **Privacy-First**: Only works in V1 mode with OAuth authentication

package/dist/api/TrainlyClient.d.ts

@@ -17,6 +17,7 @@ export declare class TrainlyClient {
     connect(): Promise<void>;
     ask(question: string, options?: {
         includeCitations?: boolean;
+        scope_filters?: Record<string, string | number | boolean>;
     }): Promise<QueryResponse>;
     upload(file: File, scopeValues?: Record<string, string | number | boolean>): Promise<UploadResult>;
     bulkUploadFiles(files: File[], scopeValues?: Record<string, string | number | boolean>): Promise<BulkUploadResult>;

package/dist/api/TrainlyClient.js

@@ -142,7 +142,7 @@ var TrainlyClient = /** @class */ (function () {
     };
     TrainlyClient.prototype.ask = function (question_1) {
         return __awaiter(this, arguments, void 0, function (question, options) {
-            var response_1, error, data_1, url, headers, body, response, error, data;
+            var params, response_1, error, data_1, url, headers, body, response, error, data;
             if (options === void 0) { options = {}; }
             return __generator(this, function (_a) {
                 switch (_a.label) {
@@ -151,6 +151,15 @@ var TrainlyClient = /** @class */ (function () {
                             throw new Error("Not connected. Call connect() or connectWithOAuthToken() first.");
                         }
                         if (!(this.isV1Mode && this.config.appId)) return [3 /*break*/, 5];
+                        params = {
+                            messages: JSON.stringify([{ role: "user", content: question }]),
+                            response_tokens: "150",
+                        };
+                        // Add scope filters if provided
+                        if (options.scope_filters &&
+                            Object.keys(options.scope_filters).length > 0) {
+                            params.scope_filters = JSON.stringify(options.scope_filters);
+                        }
                         return [4 /*yield*/, fetch("".concat(this.config.baseUrl, "/v1/me/chats/query"), {
                                 method: "POST",
                                 headers: {
@@ -158,10 +167,7 @@ var TrainlyClient = /** @class */ (function () {
                                     "X-App-ID": this.config.appId,
                                     "Content-Type": "application/x-www-form-urlencoded",
                                 },
-                                body: new URLSearchParams({
-                                    messages: JSON.stringify([{ role: "user", content: question }]),
-                                    response_tokens: "150",
-                                }),
+                                body: new URLSearchParams(params),
                             })];
                     case 1:
                         response_1 = _a.sent();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@trainly/react",
-  "version": "1.4.0",
-  "description": "Dead simple RAG integration for React apps with OAuth authentication",
+  "version": "1.4.1",
+  "description": "Dead simple RAG integration for React apps with OAuth authentication and custom scopes",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -28,7 +28,11 @@
     "document-chat",
     "file-management",
     "file-upload",
-    "file-deletion"
+    "file-deletion",
+    "custom-scopes",
+    "scope-filtering",
+    "data-segmentation",
+    "multi-tenant"
   ],
   "author": "Trainly",
   "license": "MIT",