موصل Linear

اربط مساحة عمل Linear الخاصة بك بـ Brevo لتتبع المشاكل التي تواجه العملاء، وإشعارات تحديثات المنتج، وحملات معالم التطوير عبر Tajo.

نظرة عامة

الميزات

• مزامنة أحداث المشاكل - إعادة توجيه أحداث إنشاء وتحديث وإكمال المشاكل إلى جداول زمنية لجهات اتصال Brevo
• تتبع معالم المشاريع - تشغيل حملات Brevo عندما تصل المشاريع إلى معالم رئيسية
• ربط مشاكل العملاء - ربط مشاكل Linear بجهات اتصال Brevo لرؤية الدعم
• التقسيم القائم على التسميات - ربط تسميات Linear بسمات جهات اتصال Brevo
• تحليلات الدورات - مزامنة بيانات إكمال السبرنت/الدورات لتقارير أداء الفريق
• أتمتة مدفوعة بـ Webhook - إعادة توجيه الأحداث في الوقت الفعلي عبر webhooks الخاصة بـ Linear

المتطلبات المسبقة

قبل أن تبدأ، تأكد من توفر ما يلي:

1. مساحة عمل Linear مع وصول المسؤول
2. Personal API key أو تطبيق OAuth مُعدّ
3. حساب Brevo مع وصول API
4. حساب Tajo مع اشتراك نشط

المصادقة

يدعم Linear مفاتيح Personal API وOAuth 2.0.

الخيار 1: Personal API Key

1. اذهب إلى Linear > Settings > API > Personal API keys
2. انقر على Create key
3. سمّه “Tajo Integration”
4. انسخ المفتاح المُولَّد (يبدأ بـ lin_api_)

curl -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name email } }"}'

الخيار 2: OAuth 2.0

للتكاملات التي تخدم مساحات عمل متعددة:

1. أنشئ تطبيق OAuth في linear.app/settings/api/applications
2. اضبط redirect URI: https://app.tajo.io/callbacks/linear
3. اطلب النطاقات: read، write، issues:create، comments:create

الاتصال بـ Tajo

# Using Personal API Key
tajo connectors install linear \
  --api-key $LINEAR_API_KEY

# Using OAuth
tajo connectors install linear \
  --client-id $LINEAR_CLIENT_ID \
  --client-secret $LINEAR_CLIENT_SECRET

الإعداد

الإعداد الأساسي

connectors:
  linear:
    enabled: true

    sync:
      issues: true
      projects: true
      cycles: true
      users: true

    teams:
      - key: "ENG"
        sync_to_list: 38
      - key: "SUPPORT"
        sync_to_list: 39

    issue_states:
      - Backlog
      - Todo
      - "In Progress"
      - Done
      - Canceled

ربط الحقول

اربط بيانات المستخدمين والمشاكل في Linear بسمات Brevo:

field_mapping:
  # User fields
  id: LINEAR_USER_ID
  email: email
  name: FIRSTNAME

  # Issue metrics mapped to contact events
  last_issue_identifier: LAST_LINEAR_ISSUE
  last_issue_state: LAST_ISSUE_STATUS
  last_issue_priority: LAST_ISSUE_PRIORITY
  total_issues: LINEAR_ISSUE_COUNT

  # Project data
  current_project: ACTIVE_PROJECT
  team_key: LINEAR_TEAM

ربط الأحداث

event_mapping:
  Issue.create: ISSUE_CREATED
  Issue.update: ISSUE_UPDATED
  Issue.remove: ISSUE_DELETED
  Comment.create: COMMENT_ADDED
  Project.update: PROJECT_UPDATED
  Cycle.update: CYCLE_UPDATED

نقاط نهاية API

يستخدم Linear نقطة نهاية GraphQL واحدة. الاستعلامات والطفرات الرئيسية التي يستخدمها Tajo:

مثال على استعلام GraphQL

query GetIssues($filter: IssueFilter, $first: Int, $after: String) {
  issues(filter: $filter, first: $first, after: $after) {
    nodes {
      id
      identifier
      title
      state { name }
      priority
      assignee { email name }
      labels { nodes { name } }
      createdAt
      updatedAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

أمثلة البرمجة

تهيئة الموصل

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

await tajo.connectors.connect('linear', {
  apiKey: process.env.LINEAR_API_KEY
});

مزامنة المشاكل

await tajo.connectors.sync('linear', {
  type: 'incremental',
  resources: ['issues'],
  teams: ['ENG', 'SUPPORT'],
  since: '2024-01-01'
});

const status = await tajo.connectors.status('linear');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T18:00:00Z',
//   issuesTracked: 3200,
//   projectsMonitored: 8,
//   usersLinked: 45
// }

معالجة Webhooks الخاصة بـ Linear

app.post('/webhooks/linear', async (req, res) => {
  const event = req.body;

  // Verify webhook signature
  const signature = req.get('Linear-Signature');
  if (!verifyLinearSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  await tajo.connectors.handleWebhook('linear', {
    type: event.type,
    action: event.action,
    payload: {
      issueId: event.data?.id,
      identifier: event.data?.identifier,
      title: event.data?.title,
      state: event.data?.state?.name,
      assigneeEmail: event.data?.assignee?.email
    }
  });

  res.status(200).send('OK');
});

إنشاء مشكلة من حدث Brevo

// Create a Linear issue when a Brevo contact submits a request
tajo.events.on('contact.event', async (event) => {
  if (event.name === 'FEATURE_REQUEST') {
    await tajo.connectors.create('linear', {
      teamId: 'ENG',
      title: `Feature Request: ${event.data.subject}`,
      description: event.data.description,
      priority: 3,
      labelIds: ['feature-request']
    });
  }
});

حدود المعدل

يفرض Linear حدود معدل على GraphQL API الخاص به:

يُرجع Linear 429 Too Many Requests مع ترويسة Retry-After عند تجاوز الحدود.

استكشاف الأخطاء

المشكلات الشائعة

وضع التصحيح

connectors:
  linear:
    debug: true
    log_level: verbose
    log_queries: true

اختبار الاتصال

tajo connectors test linear
# ✓ GraphQL API connection successful
# ✓ Workspace access verified
# ✓ Team list readable
# ✓ Issue query operational
# ✓ Webhook registration available

أفضل الممارسات

1. استخدم webhooks للوقت الفعلي - سجّل webhooks بدلاً من الاستطلاع لتغييرات المشاكل
2. رشّح حسب الفريق - زامن فقط المشاكل من الفرق ذات الصلة لتقليل استخدام API
3. حسّن استعلامات GraphQL - اطلب الحقول المطلوبة فقط للبقاء ضمن حدود التعقيد
4. اربط التسميات بالشرائح - استخدم تسميات Linear لقيادة تقسيم جهات اتصال Brevo
5. تعامل مع الترقيم - تحقق دائمًا من hasNextPage واستخدم endCursor لبيانات كاملة
6. تحقق من توقيعات webhook - تحقق دائمًا من ترويسة Linear-Signature

الأمان

• مصادقة مفتاح API - مفاتيح شخصية محددة النطاق بمساحة العمل
• OAuth 2.0 - تدفق تفويض آمن للتكاملات متعددة مساحات العمل
• HTTPS فقط - جميع اتصالات API مشفرة عبر TLS 1.2+
• توقيعات Webhook - التحقق من التوقيع القائم على HMAC
• التخزين المشفر - مفاتيح API مشفرة في حالة السكون في Tajo
• امتثال SOC 2 - منصة Linear معتمدة SOC 2 Type II

موارد ذات صلة

• موصل GitHub
• موصل Jira
• موصل Notion
• Brevo Contacts API