أتمتة نشر الكتيّبات التفاعلية في CI/CD باستخدام واجهة FlipLink CLI

إذا كان ملف PDF موجوداً داخل مستودعك — عرض ملاحظات إصدار، أو كتالوج منتجات، أو تقرير ربع سنوي — فمن المنطقي أن يكون نشر النسخة التفاعلية منه جزءاً من نفس عملية البناء التي تُنتج ملف PDF. لا لوحة تحكم، ولا رفع يدوي، ولا سؤال "هل تذكّر أحدهم تحديث الكتيّب التفاعلي؟" صُمّمت واجهة FlipLink CLI لهذا الغرض تحديداً: تعمل بلا واجهة رسومية، وتستوثق من متغيّر بيئي، وتُعيد رموز خروج نظيفة يستطيع الخط أن يتفرّع بناءً عليها.

يوضّح هذا الدليل خطّ CI/CD بسيطاً ومحايداً للمنصّات يبني ملف PDF، ينشئ الكتيّب التفاعلي، ينشره، ثم يلتقط رابطه المباشر.

لماذا تُجري النشر داخل CI

لوحة التحكم رائعة لعمليات الرفع المنفردة، لكن الخط أفضل عندما يكون العمل قابلاً للتكرار:

• قابل للتكرار والتدقيق — تُنفَّذ الخطوات نفسها في كل مرة، ومُسجَّلة في سجل CI لديك.
• لا لوحة تحكم، ولا خطوة بشرية — لا أحد مضطر لتذكّر الرفع بعد كل إصدار.
• مصدر واحد للحقيقة — ملف PDF في المستودع هو ما يُشحن، فلا يبتعد الكتيّب التفاعلي عن المستند أبداً.
• افشل بصوت عالٍ — إذا تعطّل النشر، يصبح البناء أحمر بدلاً من شحن كتيّب قديم بصمت.

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

الخطوة 1: خزّن مفتاح API كسرٍّ في CI

تقرأ واجهة CLI مفتاحك من متغيّر البيئة FLIPLINK_API_KEY داخل CI (ترتيب البحث عنه هو: المتغيّر البيئي → ملف الإعداد → القيمة الافتراضية). احصل على مفتاح بتسجيل الدخول على go.fliplink.me وفتح صفحة Subscription.

أضِفه كسرٍّ لدى مزوّد CI الخاص بك — لا تُودِعه في المستودع أبداً، ولا تطبعه في السجلات. ثم اعرضه للمهمة بصفته متغيّراً بيئياً:

# Provided by your CI's secret store, not hard-coded
export FLIPLINK_API_KEY="$CI_SECRET_FLIPLINK_API_KEY"

تحقّق سريع من أن الاستيثاق يعمل قبل البدء بالعمل الفعلي:

fliplink whoami

إذا كان المفتاح مفقوداً أو خاطئاً، يخرج هذا الأمر برمز غير صفري ويتوقّف خطّك مبكراً — وهذا تماماً ما تريده.

الخطوة 2: خطّ بسيط

إليك خطّاً عاماً محايداً للمنصّات (YAML تقريبي — طابِق المفاتيح على أي CI تستخدمه). وللحصول على نسخة GitHub Actions تُشغَّل عند الإصدار تحديداً، راجع شرح GitHub Actions عند الإصدار.

pipeline:
  publish-flipbook:
    image: node:20
    secrets:
      - FLIPLINK_API_KEY        # injected from the CI secret store
    steps:
      - name: Install the CLI
        run: npm install -g fliplink-cli

      - name: Build the PDF
        run: ./scripts/build-report.sh   # your build that emits ./dist/report.pdf

      - name: Verify auth
        run: fliplink whoami

      - name: Create the flipbook
        run: |
          ID=$(fliplink flipbook create ./dist/report.pdf \
                 --title "Quarterly Report" --name quarterly \
                 --json | jq -r '.ID')
          echo "FLIPBOOK_ID=$ID" >> "$PIPELINE_ENV"

      - name: Publish the flipbook
        run: fliplink flipbook publish "$FLIPBOOK_ID"

      - name: Capture the share URL
        run: |
          URL=$(fliplink flipbook share-link "$FLIPBOOK_ID" \
                  --json | jq -r '.URL')
          echo "Published: $URL"

يتلخّص التدفّق في أربعة أوامر فعلية: بناء ملف PDF، ثم fliplink flipbook create، ثم fliplink flipbook publish، ثم fliplink flipbook share-link. وكل ما عداها ليس سوى توصيلات يوفّرها CI لديك.

الخطوة 3: التقط معرّف الكتيّب التفاعلي ورابطه

الحيلة الأساسية هي --json. يقبلها أي أمر في واجهة FlipLink CLI ويطبع JSON خاماً، تمرّره إلى jq لتستخرج بالضبط الحقل الذي تحتاجه:

# Create and grab the new flipbook's ID
ID=$(fliplink flipbook create ./dist/report.pdf \
       --title "Quarterly Report" --name quarterly \
       --json | jq -r '.ID')

# Publish it
fliplink flipbook publish "$ID"

# Grab the public share URL to post in Slack, an email, or a release note
URL=$(fliplink flipbook share-link "$ID" --json | jq -r '.URL')

مرّر $ID بين الخطوات بأي وسيلة يُشارك بها CI لديك حالته — متغيّر مُخرَج، أو ملف بيئة، أو مُخرَج مكتوب. ولمزيد من أنماط jq — ترشيح القوائم، واستخراج الحقول المتداخلة، وبناء الجداول — راجع كتابة نصوص برمجية لواجهة CLI باستخدام jq.

🚀

جرّب FlipLink مجاناً

حوّل ملف PDF خلال ثوانٍ. لا تسجيل ولا بطاقة ائتمان — ارفع ملفك وانطلق.

Drop your PDF here or click to browse

الحجم الأقصى 40MB

الباقات المدفوعة من $39 ترفع هذا الحد إلى 150 MB.

الخطوة 4: افشل بسرعة عند رموز الخروج

الخطّ لا يكون جيداً إلا بقدر جودة معالجته للأخطاء. تمنحك واجهة CLI ثلاثة رموز خروج لتتفرّع بناءً عليها:

• 0 — نجاح
• 1 — خطأ في الطلب أو في HTTP (شبكة معطوبة، فشل استيثاق 401، رفع تجاوز الحجم)
• 2 — خطأ تطبيقي (أعادت واجهة API ‏Result: ERROR، مثل مشكلة في التحقق من الصحة)

تُوقِف معظم مشغّلات CI الخطوة تلقائياً عند أي خروج غير صفري، وهو ما تريده عادةً. وإذا احتجت إلى تفاعل مختلف بحسب كل رمز، فتفرّع صراحةً:

set -euo pipefail

if fliplink flipbook publish "$ID" --json; then
  echo "Published OK"
else
  code=$?
  if [ "$code" -eq 2 ]; then
    echo "FlipLink rejected the request (application error)" >&2
  else
    echo "Request/HTTP error talking to FlipLink" >&2
  fi
  exit "$code"
fi

لاحظ أن واجهة FlipLink API تُعيد أخطاء العمل بصيغة HTTP 200 مع Result: ERROR في جسم الاستجابة — وقد ربطتها واجهة CLI مسبقاً برمز الخروج 2 نيابةً عنك، فيكفي تحقّق نظيف من رمز الخروج. لست مضطراً لتحليل رموز الحالة يدوياً.

الخطوة 5: أبلِغ عند النجاح

بعد أن تلتقط الرابط، تكون الخطوة الأخيرة مجرد إبلاغ أحدهم. الرابط نص بسيط، فأي أداة إشعار تفي بالغرض:

URL=$(fliplink flipbook share-link "$ID" --json | jq -r '.URL')

curl -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d "{\"text\": \"New flipbook published: $URL\"}"

استبدِل استدعاء curl ببريد إلكتروني، أو تعليق على GitHub، أو كتابة في سجل التغييرات لديك — والنمط نفسه. ولأن كل خطوة تفشل بسرعة، لا يُطلَق هذا الإشعار إلا حين ينجح النشر فعلاً.

الخلاصة

هذا هو النمط بأكمله: خزّن المفتاح كسرٍّ، ثبّت واجهة CLI، ابنِ ملف PDF، ثم create → publish → التقط الرابط عبر --json | jq، مع رموز الخروج تحرس كل خطوة. إنه صغير بما يكفي ليُدرَج في أي خط، وموثوق بما يكفي لتنساه — وهذا هو المغزى من الأتمتة والتكاملات.

جديد على واجهة CLI؟ ابدأ بـالبدء مع واجهة FlipLink CLI، ثم عُد ووصّلها بعملية البناء لديك.

قراءات ذات صلة

• توثيق واجهة FlipLink CLI
• البدء مع واجهة FlipLink CLI
• GitHub Actions: انشر كتيّباً تفاعلياً عند الإصدار
• كتابة نصوص برمجية لواجهة FlipLink CLI باستخدام jq
• الأتمتة والتكاملات
• مرجع واجهة FlipLink API