@plugable-io/js 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,126 @@
+# @plugable-io/js
+
+JavaScript/TypeScript client for the Plugable File Management API.
+
+## Installation
+
+```bash
+npm install @plugable-io/js
+```
+
+## Usage
+
+### Bucket Usage Patterns
+
+When creating a bucket, you can choose a usage pattern that dictates how files are accessed and isolated:
+
+- **Public**: Files are publicly readable by anyone (no auth token required). However, only authenticated users (your end-users) can upload files.
+- **Organization**: Files are isolated by `org_id`. Users can only access files belonging to their organization (as defined in their auth token).
+- **Personal**: Files are isolated by `owner_id`. Users can only access their own files.
+
+### Authentication
+
+We work with your auth provider, to simplify the process of integration.
+Currently we support:
+- Clerk
+- Supabase
+- Firebase Auth
+
+Please setup provider on admin first.
+
+If you would like to see any other providers supported, please let us know.
+
+### Initialization
+
+Initialize the client with your Bucket ID and a function to retrieve the user's authentication token.
+
+```typescript
+import { BucketClient } from '@plugable-io/js';
+
+const client = new BucketClient({
+  bucketId: 'YOUR_BUCKET_ID',
+  // Function that returns a Promise resolving to the auth token (e.g., from Clerk, Supabase, etc.). It should return a valid JWT token.
+  getToken: async () => {
+    // Example: return await auth.getToken();
+    return 'user-jwt-token';
+  }
+});
+```
+
+### File metadata
+
+You can attach custom metadata to your files. This is useful for storing external IDs, tags, or other application-specific data. You can later search for files based on this metadata.
+
+**Limitations:**
+- **Size**: Maximum 5KB of JSON data.
+- **Structure**: Must be a flat object (no nested objects).
+- **Arrays**: Arrays are supported, but they cannot contain objects.
+### Uploading a File
+
+You can upload a file using the `upload` method. You can also pass metadata that you can use for search later, such as external IDs or tags. 
+
+```typescript
+const fileInput = document.querySelector('input[type="file"]');
+const file = fileInput.files[0];
+
+try {
+  const uploadedFile = await client.upload(file, {
+    metadata: {
+      custom_key: 'custom_value'
+    },
+    onProgress: (percent) => {
+      console.log(`Upload progress: ${percent}%`);
+    }
+  });
+  console.log('File uploaded:', uploadedFile);
+} catch (error) {
+  console.error('Upload failed:', error);
+}
+```
+
+### Listing Files
+
+The results depend on your bucket's usage pattern:
+- **Public**: Returns all files in the bucket.
+- **Organization**: Returns files matching the user's `org_id`.
+- **Personal**: Returns files matching the user's `owner_id`.
+
+```typescript
+// Example: Find all invoices for a specific order
+const response = await client.list({
+  metadata: {
+    type: 'invoice',
+    order_id: 'ord_12345'
+  }
+});
+```
+
+console.log('Files:', response.files);
+```
+
+### Getting a File
+
+```typescript
+const file = await client.get('file_id');
+console.log('File details:', file);
+```
+
+### Updating File Metadata
+
+```typescript
+const updatedFile = await client.update('file_id', {
+  metadata: {
+    new_key: 'new_value'
+  }
+});
+```
+
+### Deleting a File
+
+```typescript
+await client.delete('file_id');
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plugable-io/js",
-    "version": "0.0.1",
+    "version": "0.0.2",
     "description": "JavaScript client for Plugable File Management API",
     "main": "dist/index.js",
     "module": "dist/index.mjs",