SDK تخزين ملفات full-stack: واجهة API واحدة من خادم Next.js إلى متصفح React

تخزين الملفات full-stack غالباً ثلاث تنفيذات: مسار رفع على الخادم، نموذج في المتصفح، ولوحة تتحدث إلى API آخر. Files SDK يعامل ذلك كمشكلة واحدة—واجهة تخزين من الخادم إلى المتصفح.

إذا تقيّم **SDK تخزين ملفات full-stack** لتطبيق Next.js أو بوابة عميل، هذا الإصدار يستحق النظر: gateway وعميل متصفح ومحولات ومكونات shadcn اختيارية على نفس الأفعال.

gateway واحد، أسطح متعددة

المركز: **`@files-sdk/api`**. نقطة نهاية واحدة لـ upload وdownload وlist وsearch وurl وcopy وmove وdelete وcapabilities وروابط موقّعة.

الخادم: **`@files-sdk/next`** و**`@files-sdk/hono`** وExpress وFastify وKoa وElysia وNitro وSvelteKit وAstro وBun وDeno. العميل: **`createFilesClient`**؛ **`useFiles`** لـ React وVue وSvelte مع **`useList`** و**`useFile`** و**`useSearch`**. مع **`versioning()`** أو **`softDelete()`**: إصدارات واستعادة وسلة مهملات وpurge.

لماذا تفشل التكدسات المنفصلة

Route handler + dropzone يكفي حتى presign وRange وسلة المهملات أو صلاحيات البادئة. بدون **gateway API**، كل ميزة مسار جديد وتتباعد auth.

Auth والنقل

**Deny-by-default** لكل عملية: بادئات وانتهاء صلاحية وread-only وallowlists للمصدر. التحميل redirect أو **proxy stream**؛ proxy يدعم **Range/206** ويوقف القراءة عند انقطاع العميل. رفع **presign → complete** مع fallback proxy.

محولات الخادم

لـ **Files SDK Next.js**: مسار واحد بمجموعة الأفعال الكاملة. نفس العقد على Hono وExpress—auth مرة واحدة، عميل متطابق على Vercel أو VPS.

React hooks

**`createFilesClient`** مtyped؛ **`useFiles`** مع تقدم وأخطاء. Versioning وsoft delete في نفس API العميل—not طبقة admin منفصلة.

registry shadcn/ui

مكونات على **`useFiles`**: dropzone ومتصفح + breadcrumbs وsearch وpreview ومشاركة وتقدم وإجراءات وسجل إصدارات وسلة مهملات.

متى SDK ومتى custom

• رفع المتصفح + معالجة الخادم في namespace واحد
• Presign وproxy بدون codebaseين
• Versioning أو trash كمتطلب منتج
• أطر متعددة، سياسة bucket واحدة
• UI shadcn بدون file manager مخصص

قائمة تحقق

• تركيب **`@files-sdk/api`**
• قواعد deny-by-default
• Redirect vs proxy downloads
• **`createFilesClient`** + allowlists
• **`useFiles`** في النماذج والإدارة
• shadcn: dropzone أولاً
• اختبار presign على شبكات بطيئة

للوكالات

بوابات العملاء ومكتبات الأصول تصطدم بصلاحيات مخصصة. **SDK full-stack** يوحّد upload وlist وsearch وdelete.

الخلاصة

رهان **one-storage-API**: gateway ومحولات و**`createFilesClient`** و**`useFiles`** وshadcn—نفس أفعال Files. رأي ثانٍ في بنية الرفع؟ تواصل معنا.