Arsitektur Dokumentasi

Ringkasan

Dokumen ini menjelaskan ADMIN / TERAUTENTIKASI API Membership & Paywall untuk Tulis. Endpoint ini mengelola tingkatan langganan dan langganan pengguna dalam sebuah workspace. Endpoint ini terdaftar di bawah /api pada tenantGroup (grup rute terbatas workspace) dan memerlukan autentikasi JWT Bearer plus identitas workspace (X-Workspace-ID atau subdomain).

ADMIN (JWT) — BUKAN PUBLIK Setiap endpoint di bawah dilindungi oleh Authorization: Bearer *** + X-Workspace-ID. Mereka berbeda dari endpoint PUBLIK posting (di bawah /v1, dilindungi oleh kunci API). Jangan mencampuradukkan kedua model auth tersebut.

Rute dihubungkan melalui routes.RegisterMembershipRoutes(tenantGroup, ...), mendaftarkan:

1. GET /api/membership/tiers

• Auth: ADMIN (JWT Bearer) + workspace (X-Workspace-ID)
• Deskripsi: Melihat daftar tingkatan langganan yang tersedia untuk workspace saat ini. Setiap tingkatan menjelaskan nama, harga, fitur yang disertakan, dan apakah itu tingkatan bawaan. price sebesar 0 mewakili tingkatan gratis.

Contoh respons (representatif):

[
  {
    "id": "3f1c2d4e-9a01-4b2c-8d33-1a2b3c4d5e6f",
    "name": "Gratis",
    "price": 0,
    "features": "[\"read_public\", \"comment\"]",
    "is_default": true
  },
  {
    "id": "a7b8c9d0-1234-4567-89ab-cdef01234567",
    "name": "Premium",
    "price": 9900,
    "features": "[\"read_public\", \"comment\", \"premium_posts\", \"no_ads\"]",
    "is_default": false
  }
]

Bidang features dikembalikan sebagaimana disediakan oleh backend (string JSON atau array tergantung penyimpanan). Perlakukan bentuknya sebagai representatif.

curl:

curl -X GET "https://<tenant>.tulis.app/api/membership/tiers" \
  -H "Authorization: Bearer ***" \
  -H "X-Workspace-ID: <workspace-id>"

2. POST /api/membership/tiers

• Auth: ADMIN (JWT Bearer) + workspace (X-Workspace-ID), dengan peran admin untuk membuat
• Deskripsi: Membuat tingkatan langganan baru untuk workspace.

Badan permintaan (representatif):

{
  "name": "Premium",
  "price": 9900,
  "features": "[\"read_public\", \"comment\", \"premium_posts\", \"no_ads\"]",
  "is_default": false
}

Contoh respons (representatif):

{
  "id": "a7b8c9d0-1234-4567-89ab-cdef01234567",
  "name": "Premium",
  "price": 9900,
  "features": "[\"read_public\", \"comment\", \"premium_posts\", \"no_ads\"]",
  "is_default": false
}

curl:

curl -X POST "https://<tenant>.tulis.app/api/membership/tiers" \
  -H "Authorization: Bearer ***" \
  -H "X-Workspace-ID: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium",
    "price": 9900,
    "features": "[\"read_public\", \"comment\", \"premium_posts\", \"no_ads\"]",
    "is_default": false
  }'

3. POST /api/membership/subscribe

• Auth: ADMIN (JWT Bearer) + workspace (X-Workspace-ID)
• Deskripsi: Mendaftarkan pengguna yang terautentikasi ke tingkatan yang diberikan. Badan permintaan adalah peta sederhana dengan tier_id target.

Badan permintaan:

{
  "tier_id": "<uuid>"
}

Contoh respons:

{
  "message": "Berlangganan berhasil"
}

curl:

curl -X POST "https://<tenant>.tulis.app/api/membership/subscribe" \
  -H "Authorization: Bearer ***" \
  -H "X-Workspace-ID: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{ "tier_id": "<uuid>" }'

Hubungan dengan Konten Publik (Paywall / Visibilitas)

Posting membawa konsep visibilitas yang terkait dengan membership (fitur feat-046 "Membership/paywall"). Endpoint ADMIN membership di atas mendefinisikan tingkatan dan langganan; endpoint PUBLIK posting menegakkan visibilitas.

• Endpoint POSTING publik (GET /v1/posts, GET /v1/posts/{slugOrId}) dilindungi oleh kunci API (bukan JWT), dan mengembalikan posting published.
• Posting yang dilindungi membership diberi gate; konsultasikan pengaturan admin/visibilitas untuk bagaimana gating dikonfigurasi. API publik hanya menyajikan konten yang diizinkan untuk dilihat oleh konteks yang meminta.

Peringatan: Perilaku publik yang tepat untuk posting yang di-gate (apakah mengembalikan 401/terlarang atau hanya disembunyikan dari pembaca publik yang tidak terautentikasi) tidak diverifikasi dalam tugas ini. Yang dikonfirmasi: handler publik list/get memfilter berdasarkan status published, dan visibilitas membership ditegakkan. Jangan berasumsi mekanisme error-vs-sembunyi tertentu tanpa memeriksa implementasi handler.

Perbandingan model auth