@pol-studios/storage 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,233 @@
+# @pol-studios/storage
+
+> Storage utilities for POL applications
+
+Supabase storage integration with hooks for file uploads, URL management, and dropzone functionality. Uses tus-js-client for resumable uploads.
+
+## Installation
+
+```bash
+pnpm add @pol-studios/storage
+```
+
+## Peer Dependencies
+
+```bash
+pnpm add react @tanstack/react-query @supabase/supabase-js react-dropzone @pol-studios/db @pol-studios/utils
+```
+
+## Quick Start
+
+```tsx
+import { useUpload, useUrl, useDropzoneUpload, BUCKETS } from "@pol-studios/storage";
+
+function FileUploader() {
+  const { upload, isUploading, progress } = useUpload({
+    bucket: BUCKETS.documents,
+  });
+
+  const handleUpload = async (file: File) => {
+    const result = await upload(file, "documents/my-file.pdf");
+    console.log("Uploaded:", result);
+  };
+
+  return (
+    <div>
+      <input type="file" onChange={(e) => handleUpload(e.target.files[0])} />
+      {isUploading && <progress value={progress} max={100} />}
+    </div>
+  );
+}
+```
+
+## Subpath Exports
+
+| Path | Description |
+|------|-------------|
+| `@pol-studios/storage` | All exports (hooks, types, config) |
+| `@pol-studios/storage/hooks` | Upload hooks (useUpload, useUrl, usePath, useDropzoneUpload) |
+| `@pol-studios/storage/types` | TypeScript type definitions |
+| `@pol-studios/storage/config` | Bucket configuration (BUCKETS) |
+
+## API Reference
+
+### Hooks
+
+#### useUpload
+Upload files to Supabase storage.
+
+```tsx
+import { useUpload, useUploadWithEntity } from "@pol-studios/storage/hooks";
+
+const { upload, isUploading, progress, error } = useUpload({
+  bucket: "documents",
+  onSuccess: (result) => console.log("Uploaded:", result),
+  onError: (error) => console.error("Failed:", error),
+});
+
+// Upload a file
+await upload(file, "path/to/file.pdf");
+
+// Upload with entity association
+const { upload: uploadWithEntity } = useUploadWithEntity({
+  bucket: "attachments",
+  entityType: "project",
+  entityId: projectId,
+});
+```
+
+#### useUrl
+Get signed URLs for storage objects.
+
+```tsx
+import { useUrl } from "@pol-studios/storage/hooks";
+
+const { getUrl, url, isLoading } = useUrl({
+  bucket: "documents",
+  path: "files/document.pdf",
+  expiresIn: 3600, // 1 hour
+});
+
+// Or manually fetch URL
+const signedUrl = await getUrl("another/path.pdf");
+```
+
+#### usePath
+Manage storage paths.
+
+```tsx
+import { usePath } from "@pol-studios/storage/hooks";
+
+const { path, setPath, fullPath } = usePath({
+  bucket: "uploads",
+  basePath: "users/123",
+});
+```
+
+#### useDropzoneUpload
+Integrate with react-dropzone for drag-and-drop uploads.
+
+```tsx
+import { useDropzoneUpload } from "@pol-studios/storage/hooks";
+
+function DropzoneUploader() {
+  const {
+    getRootProps,
+    getInputProps,
+    isDragActive,
+    files,
+    upload,
+    isUploading,
+    progress,
+  } = useDropzoneUpload({
+    bucket: "uploads",
+    accept: { "image/*": [".png", ".jpg", ".jpeg"] },
+    maxFiles: 5,
+    maxSize: 10 * 1024 * 1024, // 10MB
+  });
+
+  return (
+    <div {...getRootProps()}>
+      <input {...getInputProps()} />
+      {isDragActive ? (
+        <p>Drop files here...</p>
+      ) : (
+        <p>Drag files here or click to select</p>
+      )}
+      {isUploading && <progress value={progress} max={100} />}
+    </div>
+  );
+}
+```
+
+### Configuration
+
+#### BUCKETS
+Pre-defined bucket names.
+
+```tsx
+import { BUCKETS } from "@pol-studios/storage/config";
+
+// Available buckets
+BUCKETS.documents;
+BUCKETS.images;
+BUCKETS.attachments;
+// ... etc
+```
+
+## TypeScript Types
+
+```tsx
+import type {
+  // Upload types
+  StorageUploadMetadata,
+  StorageObjectMetadata,
+  UploadInput,
+  UploadResult,
+  UseUploadOptions,
+
+  // Attachment types
+  Attachment,
+  CachedUrl,
+
+  // Path types
+  UsePathOptions,
+  UsePathResult,
+
+  // Hook return types
+  UseSupabaseUploadOptions,
+  UseSupabaseUploadReturn,
+
+  // Config types
+  BucketName,
+} from "@pol-studios/storage";
+```
+
+## Features
+
+### Resumable Uploads
+Uses tus-js-client for resumable uploads, allowing large file uploads to continue after network interruptions.
+
+```tsx
+const { upload } = useUpload({
+  bucket: "large-files",
+  resumable: true, // Enable resumable uploads
+  chunkSize: 6 * 1024 * 1024, // 6MB chunks
+});
+```
+
+### Progress Tracking
+Track upload progress in real-time.
+
+```tsx
+const { progress, bytesUploaded, totalBytes } = useUpload({
+  bucket: "uploads",
+  onProgress: ({ percentage, bytesUploaded, totalBytes }) => {
+    console.log(`${percentage}% uploaded`);
+  },
+});
+```
+
+### Entity Association
+Associate uploads with database entities.
+
+```tsx
+const { upload } = useUploadWithEntity({
+  bucket: "attachments",
+  entityType: "project",
+  entityId: "project-123",
+  onSuccess: (result) => {
+    // result includes entity association metadata
+  },
+});
+```
+
+## Related Packages
+
+- [@pol-studios/db](../db) - Database utilities and Supabase client
+- [@pol-studios/utils](../utils) - Utility functions
+- [@pol-studios/ui](../ui) - UI components including file dropzone
+
+## License
+
+UNLICENSED

package/package.json

@@ -1,24 +1,37 @@
 {
   "name": "@pol-studios/storage",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Storage utilities for POL applications",
   "license": "UNLICENSED",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist"],
-  "keywords": ["storage", "supabase", "upload", "files"],
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "storage",
+    "supabase",
+    "upload",
+    "files"
+  ],
   "exports": {
-    ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
-    "./hooks": { "import": "./dist/hooks/index.js", "types": "./dist/hooks/index.d.ts" },
-    "./types": { "import": "./dist/types/index.js", "types": "./dist/types/index.d.ts" },
-    "./config": { "import": "./dist/config/index.js", "types": "./dist/config/index.d.ts" }
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm build"
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./hooks": {
+      "import": "./dist/hooks/index.js",
+      "types": "./dist/hooks/index.d.ts"
+    },
+    "./types": {
+      "import": "./dist/types/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./config": {
+      "import": "./dist/config/index.js",
+      "types": "./dist/config/index.d.ts"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -36,9 +49,14 @@
     "moment": "^2.29.4"
   },
   "devDependencies": {
-    "@pol-studios/db": "workspace:*",
-    "@pol-studios/utils": "workspace:*",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "@pol-studios/db": "1.0.1",
+    "@pol-studios/utils": "1.0.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
   }
-}
+}