إنتقل إلى المحتوى الرئيسي

أمثلة

متاح فيProResearch

أربعة أمثلة صغيرة تستخدم مسارات حقيقية. تستخدم curl وNode 18 أو أحدث الذي يتضمن fetch مدمجًا، دون أي حزم. يذكر كل مثال النطاقات التي يحتاجها المفتاح، فأنشئ مفتاحًا بتلك النطاقات فقط. راجع المصادقة ومفاتيح API.

اضبط مفتاحك مرة واحدة في الطرفية:

export READSIRA_KEY="pk_..."

النطاقات: read:collections وwrite:bookmarks.

تحتاج الإشارة المرجعية إلى title وإلى collectionId للمجموعة التي ستوضع فيها. اعرض مجموعاتك أولًا واختر واحدة:

curl "https://api.readsira.com/api/v1/collections" \
  -H "Authorization: Bearer $READSIRA_KEY"

تحتوي الاستجابة على مجموعاتك في data. انسخ id إحداها، ثم احفظ الرابط:

curl -X POST "https://api.readsira.com/api/v1/bookmarks" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/grid-lab",
    "title": "Grid Lab: long-duration storage",
    "collectionId": "PUT-A-COLLECTION-ID-HERE",
    "tags": ["energy"]
  }'

تحتوي الاستجابة على الإشارة المرجعية الجديدة في data، بما فيها id الخاص بها. الحقل tags اختياري، وبحد أقصى 20 وسمًا. حفظ رابط يُحتسب طلبًا ضمن حدك اليومي.

قراءة تظليلات عنصر محفوظ​

النطاق: read:library.

يعثر البحث على العنصر ويعطيك documentId الخاص به. تعيد قراءة المستند highlights وtags وnotes الخاصة بك بجانب النص.

const headers = { Authorization: `Bearer ${process.env.READSIRA_KEY}` };

const search = await fetch(
  'https://api.readsira.com/rest/v2/search?' + new URLSearchParams({ q: 'long-duration storage', limit: '1' }),
  { headers },
).then((r) => r.json());

const hit = search.data.results[0];
if (!hit) throw new Error('Nothing found');

const doc = await fetch(
  `https://api.readsira.com/rest/v2/documents/${hit.documentId}?maxChars=1`,
  { headers },
).then((r) => r.json());

console.log(doc.data.title);
for (const h of doc.data.highlights) console.log('-', h.text, h.note ? `(${h.note})` : '');

يطلب maxChars=1 حرفًا واحدًا من النص، لأنك هنا تريد التظليلات فقط. تأتي التظليلات مع كل استجابة. لقراءة النص كاملًا، راجع ترقيم الصفحات.

طرح سؤال مع استشهادات​

النطاق: ask:library. يستهلك هذا ميزانية الذكاء الاصطناعي ويُحتسب ضمن الإجابات التي تحصل عليها كل شهر.

curl -X POST "https://api.readsira.com/rest/v2/ask" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "What did I save about iron-air batteries?" }'

تحتوي الاستجابة في data على answer، مع علامات مثل [1]، وعلى citations. تشير العلامة [n] إلى citations[n-1]، وفيه title وurl وquote الذي تستند إليه. تكون verified هي true عندما يُعثر على الاقتباس في المقطع المستشهد به.

مزامنة مكتبتك إلى ملف​

النطاق: read:bookmarks.

يقرأ هذا السكربت كل الإشارات المرجعية، صفحةً صفحةً، ويكتبها في readsira-library.json. وينتظر عندما تطلب الواجهة التمهل. شغّله بالأمر node sync.mjs.

import { writeFile } from 'node:fs/promises';

const BASE = 'https://api.readsira.com';
const headers = { Authorization: `Bearer ${process.env.READSIRA_KEY}` };

async function get(path) {
  for (;;) {
    const res = await fetch(BASE + path, { headers });
    if (res.status === 429) {
      const wait = Number(res.headers.get('retry-after') ?? 60);
      console.log(`Rate limited, waiting ${wait} seconds`);
      await new Promise((resolve) => setTimeout(resolve, wait * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    return (await res.json()).data;
  }
}

const bookmarks = [];
for (let page = 1; ; page++) {
  const data = await get(`/api/v1/bookmarks?page=${page}&limit=100`);
  bookmarks.push(...data.bookmarks);
  console.log(`Page ${page}: ${bookmarks.length} of ${data.total}`);
  if (!data.hasMore) break;
}

await writeFile('readsira-library.json', JSON.stringify(bookmarks, null, 2));
console.log(`Wrote ${bookmarks.length} bookmarks`);

كل تشغيل يقرأ المكتبة كاملة، فشغّله بالقدر الذي تحتاجه فقط. للحصول على نسخة من كل شيء، بما فيه الملاحظات والتظليلات، في ملف واحد، استخدم التصدير في الخصوصية وبياناتك.

نصائح​

  • افحص المسار في المرجع قبل أن تبني عليه.
  • تعامل مع 429 كما في سكربت المزامنة، وتوقف عند الأخطاء الأخرى. راجع حدود المعدل والأخطاء.
  • أبقِ المفاتيح بعيدًا عن السكربتات التي تشاركها. اقرأها من البيئة.
آخر تحديث في