تخزين SDK

يمر رفع الملفات وتنزيلها عبر endpoints في HeroMate، ما يتيح للخلفية التحقق من الصلاحيات قبل توليد عناوين URL للرفع أو عناوين التنزيل الموقّعة أو إجراءات الحذف.

طرق العميل الموصى بها

استخدم هذه الطرق لتدفقات الملفات:

• dypai.api.upload(endpoint, file, { params, onProgress })
• dypai.api.download(endpoint, body?, { fileName, params })
• dypai.api.post(endpoint, body) عندما تريد عنوان URL الموقّع أو رد التخزين يدوياً
• dypai.api.delete(endpoint, { params }) لتدفقات الحذف

الرفع

استخدم dypai.api.upload() لعمليات الرفع من المتصفح. ما زال SDK ينفّذ تدفق Smart Upload تلقائياً:

1. اطلب من endpoint عنوان URL رفع موقّعاً مسبقاً
2. ارفع الملف الثنائي مباشرة إلى R2/S3
3. أكّد الرفع عبر endpoint

const { data, error } = await dypai.api.upload('storage_files', file, {
  params: {
    operation: 'upload',
    file_path: `invoices/${file.name}`,
  },
  onProgress: (pct) => console.log(`Upload: ${pct}%`),
});

if (error) {
  console.error(error.message);
  return;
}

console.log('Real storage path:', data?.storage_path);

مهم: استخدم storage_path

أثناء الرفع قد يُلحق الخلفية UUID أو يُطبّع اسم الملف. احفظ storage_path في قاعدة بياناتك، لا file_path الأصلي.

const storedPath = data?.storage_path || data?.file_path;

التنزيل

للتنزيلات الآمنة، استدعِ endpoint في الخلفية يتحقق من الملكية ثم يُرجع عنوان URL الموقّع أو يشغّل التنزيل.

const { data, error } = await dypai.api.download(
  'download_invoice_document',
  { entity_id: invoice.id },
  { fileName: 'invoice.pdf' }
);

إذا أردت عنوان URL الموقّع يدوياً:

const { data, error } = await dypai.api.post('download_invoice_document', {
  entity_id: invoice.id,
});

const signedUrl = data?.signedUrl || data?.signed_url;

سرد الملفات

للسرد، استدعِ endpoint سير عمل يغلّف dypai_storage بـ operation: "list":

const { data, error } = await dypai.api.post('storage_files', {
  operation: 'list',
  prefix: 'invoices/2024',
});

الحذف

احذف الملفات عبر endpoint أيضاً:

const { error } = await dypai.api.delete('storage_delete_files', {
  params: { file_path: storedPath },
});

نمط الخلفية

في الخلفية، يستخدم endpoint عادة عقدة dypai_storage. يمكن لـ endpoint عام دعم الرفع أو التنزيل أو القراءة أو السرد أو الحذف عبر input.operation.

لتنزيلات المستخدم، فضّل endpoint مخصصاً يتحقق أولاً من الملكية بـ SQL ثم يستدعي dypai_storage فقط بعد ذلك.