مرجع API یکپارچگی LMS

/**
 * ArtaIntegrationClient — Node.js 18+
 * npm: فقط fetch داخلی (یا node-fetch)
 */
export class ArtaIntegrationError extends Error {
  constructor(
    message: string,
    public code: string,
    public requestId: string | null,
    public details?: Record<string, unknown>,
    public httpStatus?: number,
  ) {
    super(message);
    this.name = 'ArtaIntegrationError';
  }
}

export class ArtaIntegrationClient {
  constructor(
    private apiKey: string,
    private baseUrl = '/api',
  ) {}

  private async request<T>(
    method: string,
    path: string,
    opts?: { body?: unknown; idempotencyKey?: string; auth?: boolean },
  ): Promise<T & { requestId: string; apiVersion: string }> {
    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
    if (opts?.auth !== false) headers.Authorization = `Bearer ${this.apiKey}`;
    if (opts?.idempotencyKey) headers['Idempotency-Key'] = opts.idempotencyKey;

    const res = await fetch(`${this.baseUrl}${path}`, {
      method,
      headers,
      body: opts?.body != null ? JSON.stringify(opts.body) : undefined,
    });
    const data = await res.json();
    if (!res.ok) {
      throw new ArtaIntegrationError(
        data.error?.message ?? res.statusText,
        data.error?.code ?? 'HTTP_ERROR',
        data.requestId ?? res.headers.get('X-Request-Id'),
        data.error?.details,
        res.status,
      );
    }
    return data;
  }

async upsertStudent(input: {
  externalUserId: string;
  phone?: string;
  email?: string;
  displayName?: string;
}, opts?: { idempotencyKey?: string }) {
  return this.request('POST', '/v1/integration/students', {
    body: input,
    idempotencyKey: opts?.idempotencyKey ?? `student:${input.externalUserId}`,
  });
}

async createClass(input: {
  externalCourseId: string;
  name: string;
  teacherExternalId?: string;
  startAt: string;
  endAt: string;
  maxParticipants?: number;
}) {
  return this.request('POST', '/v1/integration/classes', {
    body: input,
    idempotencyKey: `class:${input.externalCourseId}`,
  });
}

async getClass(classId: string) {
  return this.request('GET', `/v1/integration/classes/${encodeURIComponent(classId)}`);
}

async getClassStatus(classId: string) {
  return this.request('GET', `/v1/integration/classes/${encodeURIComponent(classId)}/status`);
}

async getClassSessions(classId: string) {
  return this.request('GET', `/v1/integration/classes/${encodeURIComponent(classId)}/sessions`);
}

async getClassAttendance(classId: string, occurrenceKey?: string) {
  const q = occurrenceKey ? `?occurrenceKey=${encodeURIComponent(occurrenceKey)}` : '';
  return this.request('GET', `/v1/integration/classes/${encodeURIComponent(classId)}/attendance${q}`);
}

async getClassRecordings(classId: string, occurrenceKey?: string) {
  const q = occurrenceKey ? `?occurrenceKey=${encodeURIComponent(occurrenceKey)}` : '';
  return this.request('GET', `/v1/integration/classes/${encodeURIComponent(classId)}/recordings${q}`);
}

async downloadRecording(classId: string, recordingId: string): Promise<ArrayBuffer> {
  const res = await fetch(`${this.baseUrl}/v1/integration/classes/${encodeURIComponent(classId)}/recordings/${recordingId}/download`, {
    headers: { Authorization: `Bearer ${this.apiKey}` },
  });
  if (!res.ok) throw new Error(await res.text());
  return res.arrayBuffer();
}

async getClassFiles(classId: string) {
  return this.request('GET', `/v1/integration/classes/${encodeURIComponent(classId)}/files`);
}

async createEvent(input: Record<string, unknown>, opts?: { idempotencyKey?: string }) {
  return this.request('POST', '/v1/integration/events', { body: input, idempotencyKey: opts?.idempotencyKey });
}

async getEventStatus(eventId: string) {
  return this.request('GET', `/v1/integration/events/${encodeURIComponent(eventId)}/status`);
}

async enrollMembers(classId: string, members: { externalUserId: string; role?: 'student'|'teacher' }[]) {
  return this.request('PUT', `/v1/integration/classes/${encodeURIComponent(classId)}/members`, {
    body: { members },
  });
}

async issueLaunchUrl(classId: string, input: {
  externalUserId: string;
  role?: 'student' | 'teacher' | 'instructor';
  displayName?: string;
}) {
  return this.request('POST', `/v1/integration/classes/${encodeURIComponent(classId)}/launch-url`, {
    body: input,
  });
}

async getPlan() {
  return this.request('GET', '/v1/integration/plan');
}

async updateClass(classId: string, patch: Record<string, unknown>) {
  return this.request('PATCH', `/v1/integration/classes/${encodeURIComponent(classId)}`, { body: patch });
}

async archiveClass(classId: string) {
  return this.request('DELETE', `/v1/integration/classes/${encodeURIComponent(classId)}`);
}

async getSessionAttendance(classId: string, occurrenceKey: string) {
  return this.request('GET', `/v1/integration/classes/${encodeURIComponent(classId)}/sessions/${encodeURIComponent(occurrenceKey)}/attendance`);
}

async getEvent(eventId: string) {
  return this.request('GET', `/v1/integration/events/${encodeURIComponent(eventId)}`);
}

async updateEvent(eventId: string, patch: Record<string, unknown>) {
  return this.request('PATCH', `/v1/integration/events/${encodeURIComponent(eventId)}`, { body: patch });
}

async archiveEvent(eventId: string) {
  return this.request('DELETE', `/v1/integration/events/${encodeURIComponent(eventId)}`);
}

async getEventAttendance(eventId: string) {
  return this.request('GET', `/v1/integration/events/${encodeURIComponent(eventId)}/attendance`);
}

async getEventRecordings(eventId: string) {
  return this.request('GET', `/v1/integration/events/${encodeURIComponent(eventId)}/recordings`);
}

async issueEventLaunchUrl(eventId: string, input: { externalUserId: string; role?: string }) {
  return this.request('POST', `/v1/integration/events/${encodeURIComponent(eventId)}/launch-url`, { body: input });
}

async getUsage() {
  return this.request('GET', '/v1/integration/usage');
}

async listErrors() {
  return this.request('GET', '/v1/integration/errors', { auth: false });
}
}

// ─── مثال end-to-end ───
const client = new ArtaIntegrationClient(process.env.ARTA_API_KEY!);
await client.upsertStudent({ externalUserId: 'u1', phone: '09121234567', displayName: 'علی' });
const cls = await client.createClass({
  externalCourseId: 'c1', name: 'ریاضی', teacherExternalId: 't1',
  startAt: new Date().toISOString(),
  endAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString(),
});
await client.enrollMembers(cls.classId, [{ externalUserId: 'u1', role: 'student' }]);
const launch = await client.issueLaunchUrl(cls.classId, { externalUserId: 'u1' });
// res.redirect(302, launch.url)