API Referansı ve GraphQL

Coursio’da REST API route’ları (api.*.ts), GraphQL (GraphQL Yoga) ve Better Auth ile kimlik doğrulama/session yönetimi kullanılır. Bu sayfa tüm api.* endpoint’lerinin görev ve parametrelerini, api.graphql.ts üzerinden şema ve client entegrasyonunu ve Better Auth hook’ları ile session yönetimini özetler. Her endpoint’in ne için ve nasıl kullanıldığı, istek/yanıt formatları ve örnek çağrılar için Platform API Referansı sayfasına bakın.

REST Endpoints — api.*.ts Görevleri ve Parametreleri

Route tanımları app/routes.ts içindedir; dil prefix’i yok (/api/...).

Endpoint	Dosya	Method	Görev	Parametreler / Gövde
POST /api/graphql	api.graphql.ts	GET/POST	GraphQL sorgu ve mutation; aşağıda ayrıca açıklanır.	Body: { query, variables }
/api/auth/	api.auth.ts	*	Better Auth handler; giriş, kayıt, çıkış, OAuth, şifre sıfırlama, session.	Better Auth path’lerine göre (örn. sign-in/email, sign-up/email, sign-out, callback/google).
POST /api/stripe/webhook	api.stripe.webhook.ts	POST	Stripe webhook; checkout.session.completed, payment_intent.succeeded, subscription vb.	Stripe-Signature header; raw body imza doğrulaması.
POST /api/stripe/connect-onboarding	api.stripe.connect-onboarding.ts	POST	Stripe Connect Express onboarding; Account Link ile yönlendirme.	Form/cookie (session); redirect döner.
POST /api/instructor/update-manual-payout	api.instructor.update-manual-payout.ts	POST	TR eğitmeni: manuel ödeme bilgisi (IBAN/Payoneer) güncelleme.	FormData: details (string). Yetki: session + role instructor.
POST /api/lesson-resource-upload	api.lesson-resource-upload.ts	POST	Ders kaynağı (PDF vb.) yükleme; Bunny Storage.	FormData: lessonId, file. Yetki: eğitmen (kurs sahibi). Env: BUNNY_STORAGE_*.
POST /api/chat-image-upload	api.chat-image-upload.ts	POST	Mesajda görsel yükleme; Bunny Storage.	FormData: file (image/jpeg,png,gif,webp). Dönüş: { url }. Env: BUNNY_STORAGE_*, BUNNY_PULL_ZONE_URL.
GET /api/certificate/:id/download	api.certificate.$id.download.ts	GET	Sertifika PDF indirme.	Path: id (sertifika UUID). Yetki: session; sertifika userId eşleşmeli.
GET /api/certificates/:id/download	(aynı dosya)	GET	Aynı; plural URL (geriye dönük uyumluluk).	Aynı.
GET /api/invoice/:enrollmentId/download	api.invoice.$enrollmentId.download.ts	GET	Satın alma faturası PDF indirme.	Path: enrollmentId. Yetki: session; enrollment userId eşleşmeli.
GET /api/admin/activities	api.admin.activities.ts	GET	Admin “Tüm bildirimler” modalı; ödeme talepleri + kurs onayları.	Yetki: session + role admin. Dönüş: { activities } (JSON).
POST /api/update-progress	api.update-progress.ts	POST	Video izleme ilerlemesi (saniye) kaydı; user_lessons_progress, daily_activities, subscription_watch_logs.	JSON: userId, lessonId, courseId, instructorId, secondsWatched, isSubscription.

Not: api.exercise-resource-upload.ts ve api.quiz-resource-upload.ts projede dosya olarak vardır; routes.ts içinde route tanımı yoksa doğrudan /api/... ile erişilmez (iç kullanım veya farklı mount edilmiş olabilir). Dokümante edilen liste routes.ts’teki API route’larına göredir.

Veri için route loader, form/mutation için action kullanılır.

GraphQL Yoga — api.graphql.ts ve Şema

Dosya: app/routes/api.graphql.ts
Endpoint: POST /api/graphql (GET de desteklenir; Yoga varsayılanı).

Akış:

1. context.cloudflare.env ve getDbUrl(env) ile DB bağlantısı; initAuth(dbUrl, env) ile Better Auth.
2. auth.api.getSession({ headers: request.headers }) ile oturum alınır.
3. createYoga (graphql-yoga) ile Yoga instance: schema (app/graphql/schema.ts), graphqlEndpoint: "/api/graphql", context fonksiyonu db, request, user (session?.user + role), cloudflare (bölgesel fiyat/ülke için) döner.
4. yoga.handleRequest(request) ile istek işlenir; GET (GraphiQL/playground) ve POST (sorgu) desteklenir.

Şema tanımları: app/graphql/schema.ts

• createSchema (graphql-yoga) ile tek bir şema: typeDefs (SDL string) + resolvers (Query, Mutation, tipler).
• GraphQLContext: { db, request?, user?, cloudflare? } — resolver’lar user ile yetkilendirme, request ile cookie/header, cloudflare ile request.cf (ülke) kullanır.
• Tipler: User, Course, Enrollment, Review, Certificate, PayoutRequest, CartItem, CourseBundle vb.
• Query örnekleri: courses, courseBySlug, me, myCertificates, conversationMessages, unreadMessagesCount, admin için listeler vb.
• Mutation örnekleri: createCourse, updateCourse, toggleLessonCompletion, recordLearningActivity, requestPayout, createStripeCheckoutSession, addToCart, createReview vb.

Client entegrasyonu: Uygulama içinde fetch("/api/graphql", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query, variables }) }) ile sorgu/mutation atılır; cookie ile session gönderilir (credentials: “include”). Dil prefix’i yok; base URL’e göre /api/graphql kullanılır.

Better Auth — Kimlik Doğrulama Hook’ları ve Session Yönetimi

Base path: /api/auth
Dosya: app/routes/api.auth.ts — tüm istekler auth.handler(request) ile Better Auth’a iletilir.

Konfigürasyon: app/lib/auth.ts — betterAuth({ ... })

• basePath: /api/auth
• baseURL: env BASE_URL veya localhost
• database: Drizzle adapter (PostgreSQL); user, session, account, verification tabloları.
• socialProviders: Google (clientId, clientSecret; overrideUserInfoOnSignIn: true).
• emailAndPassword: enabled; sendResetPassword (şifre sıfırlama linki, dil destekli URL); onPasswordReset; resetPasswordTokenExpiresIn: 3600.
• emailVerification: enabled; sendOnSignUp: true; sendVerificationEmail (dil destekli verify-email URL); afterEmailVerification.
• user.additionalFields: role (string, default “student”), onboardingCompleted (boolean), stripeCustomerId (string).
• databaseHooks:
  • user.create.after: OAuth ile oluşturmada image → googleImage güncellemesi; emailVerified ise hoş geldin e-postası (sendWelcomeEmail).
  • user.update.after: Google ile giriş/güncellemede image → googleImage senkronizasyonu.

Session yönetimi: Better Auth, cookie tabanlı session kullanır. auth.api.getSession({ headers: request.headers }) ile mevcut oturum okunur; resolver’lar ve API route’ları bu session’a göre user ve yetki kontrolü yapar. Çıkış: /api/auth/sign-out (Better Auth endpoint’i).

Kullanım: Login/register sayfaları Better Auth client (örn. signIn.email, signUp.email) ile /api/auth path’lerini tetikler; callback ve redirect’ler BASE_URL ve dil path’ine göre yapılandırılır.

Özet

Konu	Açıklama
REST api.*	routes.ts’te tanımlı endpoint’ler: graphql, auth/*, stripe/webhook, stripe/connect-onboarding, instructor/update-manual-payout, lesson-resource-upload, chat-image-upload, certificate(s)/:id/download, invoice/:enrollmentId/download, admin/activities, update-progress.
GraphQL	POST /api/graphql; Yoga + schema (typeDefs + resolvers); context: db, request, user, cloudflare. Client: fetch + credentials.
Better Auth	/api/auth/* → auth.handler; Drizzle + Google + email/password + verification + reset; databaseHooks (user create/update); session cookie ile getSession.

İlgili mimari: Checkout & Webhooks (Stripe webhook), Stripe Connect (connect-onboarding), TR Payout (update-manual-payout), Öğrenme Deneyimi (update-progress), İletişim (chat-image-upload).

İlgili Dosyalar

• app/routes/api.graphql.ts — GraphQL Yoga endpoint; şema ve context.
• app/routes/api.auth.ts — Better Auth handler (tüm /api/auth/*).
• app/graphql/schema.ts — GraphQL typeDefs ve resolvers.
• app/lib/auth.ts — Better Auth yapılandırması.
• app/lib/graphql-client.ts — Uygulama içi GraphQL istemcisi.