ফোল্ডার

ফোল্ডার ড্যাশবোর্ডে আপনার আপলোড করা ফাইলগুলি সংগঠিত করে। এগুলি ডিফল্টরূপে শুধুমাত্র metadata — ফাইল তাদের নিজস্ব CID ধরে রাখে এবং IPFS-এ সরানো হয় না — কিন্তু আপনি একটি ফোল্ডার স্ন্যাপশটও করতে পারেন যাতে এটি একটি প্রকৃত UnixFS ডিরেক্টরি হিসেবে বাস্তবায়িত হয় এবং পুরো জিনিসের জন্য একটি CID পান।

কখন একটি ফোল্ডার স্ন্যাপশট করবেন

একটি ফোল্ডার স্ন্যাপশট হলো একটি একক IPFS ডিরেক্টরি CID যা ফোল্ডারের প্রতিটি ফাইল ধারণ করে, নাম দ্বারা ঠিকানাযোগ্য। এটি দিয়ে আপনি পারবেন:

• একটি URL দিয়ে সম্পূর্ণ ফোল্ডার শেয়ার করতে: https://ipfs.ninja/ipfs/{dirCid}/
• https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (বা অন্য যেকোনো গেটওয়ে) সরাসরি resolve করতে
• একটি স্ট্যাটিক সাইট হোস্ট করতে CID-টি একটি ENS contenthash-এ রাখতে
• একটি NFT কালেকশনের বেস CID হিসেবে এটি ব্যবহার করতে যাতে প্রতিটি টোকেন ipfs://{dirCid}/<id>.json রেফার করে
• অন্য যেকোনো জায়গায় ডিরেক্টরিটি পিন করতে — বিশ্বের প্রতিটি IPFS গেটওয়ে জানে কীভাবে একটি UnixFS dir CID resolve করতে হয়

স্ন্যাপশট কন্টেন্ট-অ্যাড্রেসড: অভিন্ন ফোল্ডার কন্টেন্ট সবসময় একই CID তৈরি করে। আপনি পরিবর্তন করেননি এমন একটি ফোল্ডার পুনরায় স্ন্যাপশট করলে এটি আগে যে CID ফেরত দিয়েছিল সেটিই ফেরত দেয়। একটি ফাইল যোগ/সরানো/পুনঃনামকরণ একটি নতুন CID তৈরি করে; আগের CID পিন করা এবং resolve করার যোগ্য থাকে যতক্ষণ আপনি এর ফাইলগুলি মুছে না ফেলেন।

ফোল্ডার তৈরি করুন

POST /folders

প্যারামিটার	ধরন	প্রয়োজনীয়	বর্ণনা
name	string	হ্যাঁ	প্রদর্শন নাম।
parentFolderId	string | null	না	নেস্টেড ফোল্ডারের জন্য প্যারেন্ট ফোল্ডার ID। রুট-লেভেল ফোল্ডারের জন্য বাদ দিন।

উদাহরণ

curl -X POST https://api.ipfs.ninja/folders \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My NFT collection" }'

ফেরত দেয়:

{
  "folderId": "1f8e2c3a-…",
  "name": "My NFT collection",
  "parentFolderId": null,
  "createdAt": 1746360000000
}

নতুন-তৈরি ফোল্ডারের কোনো স্ন্যাপশট থাকে না। আপনি POST /folders/{id}/snapshot কল করার পর (নীচে দেখুন) এবং পরবর্তী GET /folders প্রতিক্রিয়ায় latestSnapshot ফিল্ডটি ফোল্ডারে দেখা যায়।

ফোল্ডারের তালিকা

GET /folders

আপনার অ্যাকাউন্টের প্রতিটি ফোল্ডার, রুট-লেভেল এবং নেস্টেড, প্রতিটির শেষ স্ন্যাপশট CID (যদি থাকে) সহ ফেরত দেয়।

[
  {
    "folderId": "1f8e2c3a-…",
    "name": "My NFT collection",
    "parentFolderId": null,
    "createdAt": 1746360000000,
    "fileCount": 42,
    "latestSnapshot": {
      "cid": "QmRZx5…",
      "takenAt": 1746421000000,
      "fileCount": 42
    }
  }
]

fileCount ফোল্ডারের বর্তমান কন্টেন্ট প্রতিফলিত করে; latestSnapshot.fileCount শেষ স্ন্যাপশটের সময়কার কন্টেন্ট প্রতিফলিত করে। যদি এগুলি ভিন্ন হয় তাহলে স্ন্যাপশট CID তবুও resolve হয় কিন্তু stale — রিফ্রেশ করতে পুনরায় স্ন্যাপশট করুন।

একটি ফাইল ফোল্ডারে সরান

PUT /files/{cid}/move

প্যারামিটার	ধরন	প্রয়োজনীয়	বর্ণনা
folderId	string | null	হ্যাঁ	টার্গেট ফোল্ডার ID, অথবা ফাইলটিকে রুটে সরাতে null।

curl -X PUT https://api.ipfs.ninja/files/Qm.../move \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "folderId": "1f8e2c3a-…" }'

একটি ফোল্ডার স্ন্যাপশট করুন (একটি UnixFS dir CID পান)

POST /folders/{folderId}/snapshot

IPFS ক্লাস্টারে ফোল্ডারটিকে একটি প্রকৃত UnixFS ডিরেক্টরি হিসেবে বাস্তবায়িত করুন এবং ফলাফলটি পিন করুন। পুরো ফোল্ডারের জন্য একটি CID ফেরত দেয়। চাইল্ডের নামগুলি প্রতিটি ফাইলের fileName থেকে আসে; ডুপ্লিকেটগুলি স্বয়ংক্রিয়ভাবে de-collide করা হয়।

কোনো অনুরোধ বডির প্রয়োজন নেই; path প্যারামিটার ফোল্ডারটি চিহ্নিত করে।

উদাহরণ

curl -X POST https://api.ipfs.ninja/folders/1f8e2c3a-.../snapshot \
  -H "X-Api-Key: bws_your_api_key_here"

ফেরত দেয়:

{
  "ok": true,
  "folderId": "1f8e2c3a-…",
  "cid": "QmRZx5VgFHDsG7ECvaKkZBS4ydmkdAkDyaKyF71RYvh8",
  "fileCount": 42,
  "sizeBytes": 8421376,
  "takenAt": 1746421000000,
  "ipfsUrl": "https://ipfs.ninja/ipfs/QmRZx5.../"
}

CID ফোল্ডারের সারিতেও সংরক্ষিত থাকে, তাই পরবর্তী GET /folders কলগুলি অন্য স্ন্যাপশট ছাড়াই এটি latestSnapshot.cid হিসেবে ফেরত দেয়।

একটি স্ন্যাপশট resolve করা

একবার একটি স্ন্যাপশট পিন হয়ে গেলে, ডিরেক্টরি CID যেকোনো IPFS গেটওয়ের মাধ্যমে resolve হয়। সবচেয়ে সহজ URL প্যাটার্ন:

https://ipfs.ninja/ipfs/{dirCid}/         → directory listing
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → that one file

ক্লাস্টার recursively পিন করে, তাই চাইল্ডরাও resolve-যোগ্য থাকে — এমনকি আপনি পরে আপনার অ্যাকাউন্ট থেকে মূল ফাইলটি মুছে ফেললেও, স্ন্যাপশটের কপি টিকে থাকে কারণ এটি ডিরেক্টরির মধ্য দিয়ে recurse করা একটি পৃথক পিন।

পুনরায় স্ন্যাপশট করা

একটি অপরিবর্তিত ফোল্ডার পুনরায় স্ন্যাপশট করলে একই CID ফেরত দেয় — ডিরেক্টরি CID কন্টেন্ট-অ্যাড্রেসড, তাই অভিন্ন কন্টেন্ট সবসময় একই হ্যাশ তৈরি করে, এবং ক্লাস্টারের পিন কল ডুপ্লিকেট চিনতে পারে এবং তার প্রান্তে কোনো কাজ করে না।

দ্রষ্টব্য: ফলাফল একই CID হলেও স্ন্যাপশট পাথটি নিজেই বিনামূল্যে নয়। প্রতিটি কল IPFS থেকে প্রতিটি ফাইলের বাইট ফেরত পড়ে এবং ক্লাস্টারের /add endpoint-এ multipart হিসেবে পুনরায় আপলোড করে — সেখানেই wrap-with-directory র‍্যাপিং হয়। সাধারণ ফোল্ডারের জন্য (≤100 ছোট ফাইল) এটি এখনও কয়েক সেকেন্ডে সম্পন্ন হয়; খুব বড় ফোল্ডারের জন্য কন্টেন্ট প্রকৃতপক্ষে পরিবর্তিত হলে তবেই স্ন্যাপশট কল করা ভালো।

কন্টেন্ট যোগ বা সরানোর পর স্ন্যাপশট কল করলে একটি ভিন্ন CID তৈরি হয়; আপনি এর অন্তর্নিহিত ফাইলগুলি না মোছা পর্যন্ত আগেরটি resolve হতে থাকে।

সীমা

• ফোল্ডারে অন্তত একটি ফাইল থাকতে হবে। খালি ফোল্ডার 400 — folder is empty ফেরত দেয়।
• multipart আপলোডে Kubo যে ফাইল-নামের অক্ষরগুলি গ্রহণ করে সেগুলি URL-এনকোডেড থাকে; আপনার ফাইলনামে স্পেস বা নন-ASCII অক্ষরের জন্য গেটওয়ে URL-এ percent-encoding প্রয়োজন হতে পারে।
• স্ন্যাপশট প্রতিটি অনন্য CID-এর জন্য ঠিক একবার আপনার প্ল্যানের পিন মোটের মধ্যে গণনা হয় — ফাইল ব্লকগুলি deduplicated, তাই স্ন্যাপশট মূলত আপনার আগে থেকে পিন করা ফাইলগুলির উপরে একটি ছোট ডিরেক্টরি নোড যোগ করে।

একটি ফোল্ডার আপডেট করুন

PUT /folders/{folderId}

প্যারামিটার	ধরন	প্রয়োজনীয়	বর্ণনা
name	string	না	নতুন প্রদর্শন নাম।
parentFolderId	string | null	না	ফোল্ডারটি re-parent করুন। null এটিকে রুটে সরায়।

একটি ফোল্ডার মুছুন

DELETE /folders/{folderId}

ফোল্ডারটি মুছে দেয় এবং এতে থাকা প্রতিটি ফাইল ও সাবফোল্ডারের মধ্য দিয়ে recursively cascade করে। পৃথক ফাইল মোছার মতো একই shared-CID সেফটি গার্ড সাপেক্ষ — যদি অন্য ব্যবহারকারীরা এখনও আপনার আপলোড করা একটি CID পিন করে রাখে, আপনার unpin তাদের জন্য এটি সরায় না।

{
  "deleted": true,
  "filesDeleted": 42,
  "foldersDeleted": 3
}

একটি ফোল্ডার/bucket-এর জন্য S3 CORS কনফিগার করুন

S3-সামঞ্জস্যপূর্ণ API-এর মাধ্যমে প্রকাশিত ফোল্ডারগুলি bucket হিসেবে কাজ করে। আপনি যদি ব্রাউজার JavaScript থেকে সেই API চালান, তাহলে ব্রাউজার preflight পাস করার জন্য bucket-এ CORS নিয়ম প্রয়োজন। একই স্টোরে দুটি সমতুল্য surface পার্সিস্ট করে:

• PUT /folders/{folderId}/cors — এই REST endpoint, JWT-প্রমাণীকৃত (ড্যাশবোর্ড দ্বারা ব্যবহৃত)
• S3 subresource PUT /{bucket}?cors — SigV4-প্রমাণীকৃত (AWS SDK দ্বারা ব্যবহৃত, s3-compatibility.md দেখুন)

এই endpoint-এ PUT-টি ফোল্ডারের নামটি এখনও claim করা না থাকলে সেটিকে একটি বৈশ্বিকভাবে-অনন্য bucket হিসেবেও claim করে।

PUT /folders/{folderId}/cors

ফোল্ডারের S3 bucket-এর জন্য CORS নিয়ম সেট করুন। প্রতি bucket-এ সর্বাধিক ৫টি নিয়ম, মোট ৬৪ KB।

প্যারামিটার	ধরন	প্রয়োজনীয়	বর্ণনা
rules	CorsRule[]	হ্যাঁ	AWS-আকারের CORS নিয়মের অ্যারে (নীচে দেখুন)। খালি নয়।
bucketName	string	না	স্পষ্ট S3 bucket নাম। ডিফল্ট ফোল্ডারের প্রদর্শন নাম। কাঙ্ক্ষিত নাম ইতিমধ্যে বৈশ্বিকভাবে claim করা থাকলে, এখানে একটি বিকল্প পাস করুন।

প্রতিটি CorsRule:

ফিল্ড	ধরন	প্রয়োজনীয়	বর্ণনা
AllowedOrigins	string[]	হ্যাঁ	অনুরোধ পাঠানোর অনুমতিপ্রাপ্ত origin। ওয়াইল্ডকার্ড সমর্থন করে (https://*.myapp.com)। যেকোনো origin-এর জন্য * ব্যবহার করুন।
AllowedMethods	string[]	হ্যাঁ	GET, HEAD, PUT, POST, DELETE-এর এক বা একাধিক।
AllowedHeaders	string[]	না	ব্রাউজার অনুরোধে যে হেডার অন্তর্ভুক্ত করতে পারে। ডিফল্ট: কোনোটিই না। সব অনুমতি দিতে ["*"] ব্যবহার করুন (AWS SDK v3-এর জন্য সুপারিশকৃত, যা Authorization, x-amz-* ইত্যাদি পাঠায়)।
ExposeHeaders	string[]	না	ব্রাউজার JavaScript-এ পাঠযোগ্য প্রতিক্রিয়া হেডার। আপনার অ্যাপের ফেরত পাওয়া CID প্রয়োজন হলে ETag এবং x-amz-meta-cid অন্তর্ভুক্ত করুন।
MaxAgeSeconds	number	না	ব্রাউজার কতক্ষণ preflight ক্যাশ করে। 0-86400। ডিফল্ট 3600।
ID	string	না	নিয়মের জন্য ফ্রি-টেক্সট লেবেল।

উদাহরণ অনুরোধ

curl -X PUT https://api.ipfs.ninja/folders/17f6dfd8-519c-4d0e-8f3a-5988a1d34ef2/cors \
  -H "Authorization: Bearer $COGNITO_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [{
      "AllowedOrigins": ["https://myapp.com", "http://localhost:3000"],
      "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"],
      "AllowedHeaders": ["*"],
      "ExposeHeaders": ["ETag", "x-amz-meta-cid", "x-amz-request-id"],
      "MaxAgeSeconds": 3600
    }]
  }'

প্রতিক্রিয়া 200 OK

{ "success": true, "rules": [ { "AllowedOrigins": ["https://myapp.com", "http://localhost:3000"], "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"], "AllowedHeaders": ["*"], "ExposeHeaders": ["ETag", "x-amz-meta-cid", "x-amz-request-id"], "MaxAgeSeconds": 3600 } ] }

GET /folders/{folderId}/cors

বর্তমান CORS নিয়মগুলি এবং bucket নাম (claim করা থাকলে) ফেরত দেয়।

{
  "rules": [ … ],
  "bucketName": "my-project"
}

DELETE /folders/{folderId}/cors

সমস্ত CORS নিয়ম সরিয়ে দেয়। নতুন নিয়ম সেট না করা পর্যন্ত bucket-এর বিরুদ্ধে ব্রাউজার preflight ব্যর্থ (fail closed) হবে।

ড্যাশবোর্ড বিকল্প

Files পেজে, প্রতিটি ফোল্ডারের অ্যাকশন মেনুতে একটি S3 CORS এন্ট্রি রয়েছে যা একটি ফর্ম-ভিত্তিক এডিটর খোলে। এই REST endpoint এবং S3 API-এর মাধ্যমে PutBucketCors-এর মতো একই আন্ডারলাইং স্টোর।