@trainly/react 1.3.1 → 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/TrainlyProvider.js

@@ -333,7 +333,7 @@ export function TrainlyProvider(_a) {
             }
         });
     }); };
-    var upload = function (file) { return __awaiter(_this, void 0, void 0, function () {
+    var upload = function (file, scopeValues) { return __awaiter(_this, void 0, void 0, function () {
         var result, err_5, errorMessage, newToken, result, refreshError_2, error_5;
         return __generator(this, function (_a) {
             switch (_a.label) {
@@ -341,7 +341,7 @@ export function TrainlyProvider(_a) {
                     _a.trys.push([0, 2, 10, 11]);
                     setIsLoading(true);
                     setError(null);
-                    return [4 /*yield*/, client.upload(file)];
+                    return [4 /*yield*/, client.upload(file, scopeValues)];
                 case 1:
                     result = _a.sent();
                     return [2 /*return*/, result];
@@ -364,7 +364,7 @@ export function TrainlyProvider(_a) {
                     return [4 /*yield*/, client.connectWithOAuthToken(newToken)];
                 case 5:
                     _a.sent();
-                    return [4 /*yield*/, client.upload(file)];
+                    return [4 /*yield*/, client.upload(file, scopeValues)];
                 case 6:
                     result = _a.sent();
                     console.log("✅ Upload succeeded after token refresh");
@@ -389,7 +389,7 @@ export function TrainlyProvider(_a) {
             }
         });
     }); };
-    var bulkUploadFiles = function (files) { return __awaiter(_this, void 0, void 0, function () {
+    var bulkUploadFiles = function (files, scopeValues) { return __awaiter(_this, void 0, void 0, function () {
         var result, err_6, errorMessage, newToken, result, refreshError_3, error_6;
         return __generator(this, function (_a) {
             switch (_a.label) {
@@ -397,7 +397,7 @@ export function TrainlyProvider(_a) {
                     _a.trys.push([0, 2, 10, 11]);
                     setIsLoading(true);
                     setError(null);
-                    return [4 /*yield*/, client.bulkUploadFiles(files)];
+                    return [4 /*yield*/, client.bulkUploadFiles(files, scopeValues)];
                 case 1:
                     result = _a.sent();
                     return [2 /*return*/, result];
@@ -420,7 +420,7 @@ export function TrainlyProvider(_a) {
                     return [4 /*yield*/, client.connectWithOAuthToken(newToken)];
                 case 5:
                     _a.sent();
-                    return [4 /*yield*/, client.bulkUploadFiles(files)];
+                    return [4 /*yield*/, client.bulkUploadFiles(files, scopeValues)];
                 case 6:
                     result = _a.sent();
                     console.log("✅ Bulk upload succeeded after token refresh");

package/dist/api/TrainlyClient.d.ts

@@ -17,9 +17,10 @@ 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): Promise<UploadResult>;
-    bulkUploadFiles(files: File[]): Promise<BulkUploadResult>;
+    upload(file: File, scopeValues?: Record<string, string | number | boolean>): Promise<UploadResult>;
+    bulkUploadFiles(files: File[], scopeValues?: Record<string, string | number | boolean>): Promise<BulkUploadResult>;
     listFiles(): Promise<FileListResult>;
     deleteFile(fileId: string): Promise<FileDeleteResult>;
     private extractChatId;

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();
@@ -218,7 +224,7 @@ var TrainlyClient = /** @class */ (function () {
             });
         });
     };
-    TrainlyClient.prototype.upload = function (file) {
+    TrainlyClient.prototype.upload = function (file, scopeValues) {
         return __awaiter(this, void 0, void 0, function () {
             var formData, response, error, data, formData, response, error, presignedResponse, error, _a, upload_url, upload_headers, formData, uploadResponse;
             return __generator(this, function (_b) {
@@ -230,6 +236,10 @@ var TrainlyClient = /** @class */ (function () {
                         if (!(this.isV1Mode && this.config.appId)) return [3 /*break*/, 5];
                         formData = new FormData();
                         formData.append("file", file);
+                        // Add scope values if provided
+                        if (scopeValues && Object.keys(scopeValues).length > 0) {
+                            formData.append("scope_values", JSON.stringify(scopeValues));
+                        }
                         return [4 /*yield*/, fetch("".concat(this.config.baseUrl, "/v1/me/chats/files/upload"), {
                                 method: "POST",
                                 headers: {
@@ -258,6 +268,10 @@ var TrainlyClient = /** @class */ (function () {
                         if (!this.config.apiKey) return [3 /*break*/, 9];
                         formData = new FormData();
                         formData.append("file", file);
+                        // Add scope values if provided
+                        if (scopeValues && Object.keys(scopeValues).length > 0) {
+                            formData.append("scope_values", JSON.stringify(scopeValues));
+                        }
                         return [4 /*yield*/, fetch("".concat(this.config.baseUrl, "/v1/").concat(this.extractChatId(), "/upload_file"), {
                                 method: "POST",
                                 headers: {
@@ -324,7 +338,7 @@ var TrainlyClient = /** @class */ (function () {
             });
         });
     };
-    TrainlyClient.prototype.bulkUploadFiles = function (files) {
+    TrainlyClient.prototype.bulkUploadFiles = function (files, scopeValues) {
         return __awaiter(this, void 0, void 0, function () {
             var formData_1, response, error, data, results, successful_uploads, total_size_bytes, _i, files_1, file, uploadResult, error_1;
             return __generator(this, function (_a) {
@@ -345,6 +359,10 @@ var TrainlyClient = /** @class */ (function () {
                         files.forEach(function (file) {
                             formData_1.append("files", file);
                         });
+                        // Add scope values if provided
+                        if (scopeValues && Object.keys(scopeValues).length > 0) {
+                            formData_1.append("scope_values", JSON.stringify(scopeValues));
+                        }
                         return [4 /*yield*/, fetch("".concat(this.config.baseUrl, "/v1/me/chats/files/upload-bulk"), {
                                 method: "POST",
                                 headers: {
@@ -386,7 +404,7 @@ var TrainlyClient = /** @class */ (function () {
                         _a.label = 7;
                     case 7:
                         _a.trys.push([7, 9, , 10]);
-                        return [4 /*yield*/, this.upload(file)];
+                        return [4 /*yield*/, this.upload(file, scopeValues)];
                     case 8:
                         uploadResult = _a.sent();
                         results.push({

package/dist/components/TrainlyUpload.d.ts

@@ -6,5 +6,6 @@ export interface TrainlyUploadProps {
     className?: string;
     onUpload?: (files: File[]) => void;
     onError?: (error: string) => void;
+    scopeValues?: Record<string, string | number | boolean>;
 }
-export declare function TrainlyUpload({ variant, accept, maxSize, multiple, className, onUpload, onError, }: TrainlyUploadProps): import("react/jsx-runtime").JSX.Element;
+export declare function TrainlyUpload({ variant, accept, maxSize, multiple, className, onUpload, onError, scopeValues, }: TrainlyUploadProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/TrainlyUpload.js

@@ -40,7 +40,7 @@ import * as React from "react";
 import { useTrainly } from "../useTrainly";
 export function TrainlyUpload(_a) {
     var _this = this;
-    var _b = _a.variant, variant = _b === void 0 ? "drag-drop" : _b, _c = _a.accept, accept = _c === void 0 ? ".pdf,.doc,.docx,.txt,.md" : _c, _d = _a.maxSize, maxSize = _d === void 0 ? "10MB" : _d, _e = _a.multiple, multiple = _e === void 0 ? false : _e, _f = _a.className, className = _f === void 0 ? "" : _f, onUpload = _a.onUpload, onError = _a.onError;
+    var _b = _a.variant, variant = _b === void 0 ? "drag-drop" : _b, _c = _a.accept, accept = _c === void 0 ? ".pdf,.doc,.docx,.txt,.md" : _c, _d = _a.maxSize, maxSize = _d === void 0 ? "10MB" : _d, _e = _a.multiple, multiple = _e === void 0 ? false : _e, _f = _a.className, className = _f === void 0 ? "" : _f, onUpload = _a.onUpload, onError = _a.onError, scopeValues = _a.scopeValues;
     var _g = useTrainly(), upload = _g.upload, isLoading = _g.isLoading;
     var _h = React.useState(false), isDragOver = _h[0], setIsDragOver = _h[1];
     var fileInputRef = React.useRef(null);
@@ -70,7 +70,7 @@ export function TrainlyUpload(_a) {
                 case 2:
                     if (!(_a < fileArray_2.length)) return [3 /*break*/, 5];
                     file = fileArray_2[_a];
-                    return [4 /*yield*/, upload(file)];
+                    return [4 /*yield*/, upload(file, scopeValues)];
                 case 3:
                     _b.sent();
                     _b.label = 4;

package/dist/types.d.ts

@@ -93,10 +93,10 @@ export interface TrainlyContextValue {
         answer: string;
         citations: Citation[];
     }>;
-    upload: (file: File) => Promise<UploadResult>;
+    upload: (file: File, scopeValues?: Record<string, string | number | boolean>) => Promise<UploadResult>;
     listFiles: () => Promise<FileListResult>;
     deleteFile: (fileId: string) => Promise<FileDeleteResult>;
-    bulkUploadFiles: (files: File[]) => Promise<BulkUploadResult>;
+    bulkUploadFiles: (files: File[], scopeValues?: Record<string, string | number | boolean>) => Promise<BulkUploadResult>;
     connectWithOAuthToken: (idToken: string) => Promise<void>;
     isLoading: boolean;
     isConnected: boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@trainly/react",
-  "version": "1.3.1",
-  "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",