@plasgos/oidc-client 0.1.0-next.1 → 0.1.0-next.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/LICENSE +4 -3
  3. package/README.md +22 -13
  4. package/dist/index.cjs +2 -2
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.d.cts +2 -2
  7. package/dist/index.d.ts +2 -2
  8. package/dist/index.js +2 -2
  9. package/dist/index.js.map +1 -1
  10. package/dist/service.cjs +1 -1
  11. package/dist/service.cjs.map +1 -1
  12. package/dist/service.d.cts +3 -3
  13. package/dist/service.d.ts +3 -3
  14. package/dist/service.js +1 -1
  15. package/dist/service.js.map +1 -1
  16. package/dist/session.cjs.map +1 -1
  17. package/dist/session.d.cts +2 -2
  18. package/dist/session.d.ts +2 -2
  19. package/dist/session.js.map +1 -1
  20. package/dist/{types-Cncksfeo.d.cts → types-JE0OMyoi.d.cts} +1 -1
  21. package/dist/{types-Cncksfeo.d.ts → types-JE0OMyoi.d.ts} +1 -1
  22. package/docs/consumers.md +90 -0
  23. package/docs/contoh-hitungcuan.md +255 -0
  24. package/docs/contoh-plaslink.md +244 -0
  25. package/docs/error.md +428 -0
  26. package/docs/examples/auth-verify-readme.ts +18 -0
  27. package/docs/examples/config-error.ts +24 -0
  28. package/docs/examples/env.ts +99 -0
  29. package/docs/examples/failure-log.ts +18 -0
  30. package/docs/examples/login-client.ts +46 -0
  31. package/docs/examples/login-flow.ts +186 -0
  32. package/docs/examples/plaslink-connect.ts +48 -0
  33. package/docs/examples/readme.ts +60 -0
  34. package/docs/examples/service-client.ts +105 -0
  35. package/docs/examples/session-store.ts +53 -0
  36. package/docs/examples/webhook-express.ts +46 -0
  37. package/docs/examples/webhook-fetch.ts +60 -0
  38. package/docs/examples/webhook-nestjs.ts +59 -0
  39. package/docs/examples/webhook-testing.ts +60 -0
  40. package/docs/examples/webhook-verifier.ts +143 -0
  41. package/docs/login-web.md +618 -0
  42. package/docs/memulai.md +339 -0
  43. package/docs/server-ke-server.md +275 -0
  44. package/docs/webhook.md +625 -0
  45. package/package.json +3 -2
@@ -0,0 +1,255 @@
1
+ # Contoh: HitungCuan (payments saja)
2
+
3
+ HitungCuan menagih langganan seller lewat payments Plasgos. Aplikasi ini **tidak punya login Plasgos**, jadi tidak memakai `createOidcClient` sama sekali. Yang dipakai hanya dua hal:
4
+
5
+ | Kebutuhan | Bagian SDK | Status |
6
+ |---|---|---|
7
+ | Membuat dan melihat payment | `createServiceClient` dari `@plasgos/oidc-client/service` | Panduan ini |
8
+ | Menerima kabar status payment (webhook) | `createWebhookVerifier` dari `@plasgos/auth-verify/webhook` | Panduan ini |
9
+
10
+ Panduan ini berjalan dari nol sampai payment pertama dan webhook-nya. Penjelasan setiap opsi ada di [`server-ke-server.md`](server-ke-server.md) dan [`webhook.md`](webhook.md).
11
+
12
+ ## 1. Prasyarat di Plasgos
13
+
14
+ Tim Plasgos menyiapkan hal berikut, sekali untuk sandbox dan sekali untuk production, lalu menyerahkan kredensialnya kepada HitungCuan ([§2](#2-yang-diterima-hitungcuan)):
15
+
16
+ 1. App `hitungcuan` di katalog aplikasi Plasgos.
17
+ 2. Purpose pembayaran `subscription` untuk app itu. Tanpa purpose, pembuatan payment dijawab `422 purpose_not_allowed`.
18
+ 3. Client service untuk app itu dengan scope `platform:self.read`, `payments:read`, `payments:write`. Refund HitungCuan dikerjakan manual, jadi client-nya tanpa `payments:refund`.
19
+ 4. URL webhook HitungCuan yang Anda berikan, beserta secret webhook (`whsec_…`) untuk URL itu.
20
+
21
+ ## 2. Yang diterima HitungCuan
22
+
23
+ | Nilai | Lewat | Env |
24
+ |---|---|---|
25
+ | Client id | Kanal secret | `PLASGOS_SERVICE_CLIENT_ID` |
26
+ | Client secret (tampil sekali) | Kanal secret | `PLASGOS_SERVICE_CLIENT_SECRET` |
27
+ | Secret webhook (tampil sekali) | Kanal secret | `PLASGOS_WEBHOOK_SECRET` |
28
+ | Issuer | Biasa | `PLASGOS_ISSUER` |
29
+ | Host API | Biasa | `PLASGOS_API_URL` |
30
+ | Audience platform, bila bukan bawaan | Biasa | `PLASGOS_AUDIENCE` |
31
+
32
+ Bila serah terima dari tim Plasgos memakai nama lain, pemetaannya:
33
+
34
+ | Nama di serah terima | Dipakai sebagai |
35
+ |---|---|
36
+ | `PLASGOS_CLIENT_ID`, `PLASGOS_CLIENT_SECRET` | `PLASGOS_SERVICE_CLIENT_ID`, `PLASGOS_SERVICE_CLIENT_SECRET` |
37
+ | `PLASGOS_TOKEN_URL` (`<issuer>/oidc/token`) | Tidak dipakai. Isi `PLASGOS_ISSUER` dengan bagian sebelum `/oidc/token`. SDK menambahkan path-nya sendiri |
38
+ | `PLASGOS_AUDIENCE` | `PLASGOS_AUDIENCE` |
39
+
40
+ ## 3. Env
41
+
42
+ Sandbox:
43
+
44
+ ```dotenv
45
+ PLASGOS_ENV=sandbox
46
+ PLASGOS_ISSUER=https://<host accounts sandbox>
47
+ PLASGOS_API_URL=https://api.sandbox.plasgos.co.id
48
+ PLASGOS_SERVICE_CLIENT_ID=<client id sandbox>
49
+ PLASGOS_SERVICE_CLIENT_SECRET=<client secret sandbox>
50
+ PLASGOS_WEBHOOK_SECRET=<secret webhook sandbox>
51
+ # PLASGOS_AUDIENCE=<hanya bila diberikan tim Plasgos>
52
+ ```
53
+
54
+ Production:
55
+
56
+ ```dotenv
57
+ PLASGOS_ENV=production
58
+ PLASGOS_ISSUER=https://accounts.plasgos.co.id
59
+ PLASGOS_API_URL=https://api.plasgos.co.id
60
+ PLASGOS_SERVICE_CLIENT_ID=<client id production>
61
+ PLASGOS_SERVICE_CLIENT_SECRET=<client secret production>
62
+ PLASGOS_WEBHOOK_SECRET=<secret webhook production>
63
+ ```
64
+
65
+ `PLASGOS_ENV` adalah pengaman. Bila `PLASGOS_ENV=sandbox` tetapi salah satu URL mengarah ke host production (atau `PLASGOS_ENV=production` dengan issuer yang bukan production), aplikasi menolak start. Lihat [`memulai.md` §5](memulai.md#sandbox-dan-production).
66
+
67
+ ## 4. Install
68
+
69
+ Install `@plasgos/oidc-client` dan `@plasgos/auth-verify` dari npmjs.com dengan nomor versi persis yang sama, tanpa token (`pnpm add @plasgos/oidc-client@<versi> @plasgos/auth-verify@<versi> --save-exact`). Aturan versi dan Docker ada di [`consumers.md`](consumers.md).
70
+
71
+ ## 5. Kode
72
+
73
+ Salin tiga file dari [folder contoh](examples/) ke aplikasi: `env.ts`, `failure-log.ts`, dan `config-error.ts`. Isinya ada di [`memulai.md`](memulai.md) dan [`server-ke-server.md`](server-ke-server.md).
74
+
75
+ **Langkah 1. Buat client saat start.**
76
+
77
+ <!-- snippet: examples/snippets/service-client.ts#create -->
78
+ ```ts
79
+ /** Create it once at start and reuse it: the token cache lives in the client. */
80
+ export function createPlasgosClient(): ServiceClient {
81
+ const env = readPlasgosEnv();
82
+ const credentials = readServiceCredentials();
83
+ return createServiceClient({
84
+ environment: env.environment,
85
+ issuer: env.issuer,
86
+ apiUrl: env.apiUrl,
87
+ backchannelUrl: env.backchannelUrl,
88
+ clientId: credentials.clientId,
89
+ clientSecret: credentials.clientSecret,
90
+ scopes: ["platform:self.read", "payments:read", "payments:write"],
91
+ resource: credentials.audience,
92
+ onFailure: logFailure,
93
+ });
94
+ }
95
+ ```
96
+ <!-- /snippet -->
97
+
98
+ Di file start aplikasi: `const plasgos = createOrExit(createPlasgosClient);`. Bila ada opsi yang salah, aplikasi berhenti dan mencetak semua masalahnya di bawah baris `Plasgos configuration is invalid:`. Bila sebuah env kosong, `env.ts` berhenti lebih dulu dengan `Environment variable <NAMA> is required`, satu variabel setiap kali.
99
+
100
+ **Langkah 2. Cek koneksi.** Jalankan sekali setelah deploy, atau jadikan bagian health check saat start.
101
+
102
+ <!-- snippet: examples/snippets/service-client.ts#self-check -->
103
+ ```ts
104
+ /** GET /v5/service/me: proves the credentials, the scope and the network path. Needs platform:self.read. */
105
+ export async function checkConnection(plasgos: ServiceClient): Promise<unknown> {
106
+ const res = await plasgos.fetch("/v5/service/me");
107
+ if (!res.ok) throw new Error(`Plasgos self check answered ${String(res.status)}`);
108
+ return res.json();
109
+ }
110
+ ```
111
+ <!-- /snippet -->
112
+
113
+ Jawaban yang benar berisi kode app (`hitungcuan`), client id, dan daftar scope. Bila gagal, lihat [§6](#6-bila-gagal).
114
+
115
+ **Langkah 3. Buat payment pertama.**
116
+
117
+ <!-- snippet: examples/snippets/service-client.ts#create-payment -->
118
+ ```ts
119
+ export interface NewPayment {
120
+ /** Your own id of the bill. Sending the same body again returns the same payment (200, not 201). */
121
+ external_ref: string;
122
+ /** A payment purpose registered for your app, for example "subscription". */
123
+ purpose: string;
124
+ amount: { amount: number; currency: "IDR" };
125
+ customer: { name: string; email: string };
126
+ }
127
+
128
+ /** POST /v5/service/payments. Needs payments:write. */
129
+ export async function createPayment(plasgos: ServiceClient, payment: NewPayment): Promise<unknown> {
130
+ const res = await plasgos.fetch("/v5/service/payments", {
131
+ method: "POST",
132
+ headers: { "Content-Type": "application/json" },
133
+ body: JSON.stringify(payment),
134
+ });
135
+ if (!res.ok) throw new Error(`Plasgos payments answered ${String(res.status)}`);
136
+ return res.json();
137
+ }
138
+ ```
139
+ <!-- /snippet -->
140
+
141
+ Pemanggilannya untuk tagihan langganan:
142
+
143
+ <!-- snippet: examples/snippets/service-client.ts#first-payment -->
144
+ ```ts
145
+ /** A subscription bill of this app, paid through Plasgos. */
146
+ export function createSubscriptionPayment(
147
+ plasgos: ServiceClient,
148
+ bill: { id: string; amountRupiah: number; sellerName: string; sellerEmail: string },
149
+ ): Promise<unknown> {
150
+ return createPayment(plasgos, {
151
+ external_ref: bill.id,
152
+ purpose: "subscription",
153
+ amount: { amount: bill.amountRupiah, currency: "IDR" },
154
+ customer: { name: bill.sellerName, email: bill.sellerEmail },
155
+ });
156
+ }
157
+ ```
158
+ <!-- /snippet -->
159
+
160
+ - Pakai id tagihan HitungCuan sebagai `external_ref`. Bila request timeout, kirim ulang body yang sama. Plasgos tidak membuat payment kedua.
161
+ - Jawaban berisi id payment (`pay_…`) dan instruksi bayar. Simpan id payment di tagihan.
162
+ - Status lunas datang lewat webhook ([§7](#7-webhook-pembayaran)). Sebagai cadangan, status bisa dibaca dengan `GET /v5/service/payments/{pay_id}` (scope `payments:read`).
163
+
164
+ ## 6. Bila gagal
165
+
166
+ | Gejala | Penyebab | Yang dilakukan |
167
+ |---|---|---|
168
+ | Aplikasi berhenti saat start dengan `Plasgos configuration is invalid:` atau `Environment variable … is required` | Env kosong, URL salah, atau `PLASGOS_ENV` tidak cocok dengan URL | Perbaiki env sesuai daftar masalah yang dicetak |
169
+ | `OidcError` `config_invalid` | Client secret salah, client dinonaktifkan, atau scope tidak dimiliki client | Periksa kredensial dan scope. Jangan diulang otomatis |
170
+ | `OidcError` `invalid_target` | Audience lingkungan itu bukan nilai bawaan | Isi `PLASGOS_AUDIENCE` dengan nilai dari tim Plasgos |
171
+ | `OidcError` `unavailable` | Jaringan, timeout, atau Plasgos sedang gangguan | Ulangi dengan jeda |
172
+ | `403 app_disabled` | App `hitungcuan` dinonaktifkan | Hubungi tim Plasgos |
173
+ | `403 insufficient_scope` | Endpoint butuh scope yang tidak dimiliki client | Minta scope ke tim Plasgos, lalu tambahkan di `scopes` |
174
+ | `422 purpose_not_allowed` | Purpose belum didaftarkan atau dinonaktifkan | Minta tim Plasgos mendaftarkan purpose |
175
+
176
+ Rincian setiap `reason` ada di [`error.md`](error.md).
177
+
178
+ ## 7. Webhook pembayaran
179
+
180
+ Plasgos mengirim event payment (misalnya `payment.paid`, `payment.expired`) ke URL webhook HitungCuan. Setiap kiriman ditandatangani dengan secret webhook. HitungCuan memeriksa tanda tangan itu dengan `@plasgos/auth-verify/webhook` sebelum mempercayai isinya. Aturan lengkapnya ada di [`webhook.md`](webhook.md).
181
+
182
+ Salin juga `webhook-verifier.ts` dan file route untuk framework Anda (`webhook-express.ts`, `webhook-nestjs.ts`, atau `webhook-fetch.ts`) dari [folder contoh](examples/). Buat tabel `plasgos_webhook_events` ([`webhook.md` §7](webhook.md#7-dedup-di-transaksi-yang-sama)).
183
+
184
+ **Langkah 1. Buat verifier saat start.**
185
+
186
+ <!-- snippet: examples/snippets/webhook-verifier.ts#create -->
187
+ ```ts
188
+ /** Payments webhooks. Create it once at start: a wrong option throws one ConfigError there. */
189
+ export function createPaymentsWebhookVerifier(): WebhookVerifier {
190
+ return createWebhookVerifier({
191
+ environment: readEnvironment(),
192
+ secrets: readWebhookSecrets("PLASGOS_WEBHOOK_SECRET"),
193
+ preset: presets.payments,
194
+ });
195
+ }
196
+ ```
197
+ <!-- /snippet -->
198
+
199
+ Di file start aplikasi: `const verifier = createOrExit(createPaymentsWebhookVerifier);`. Secret-nya dibaca dari `PLASGOS_WEBHOOK_SECRET` ([§3](#3-env)).
200
+
201
+ **Langkah 2. Buat route dengan body mentah.** Tanda tangan dihitung atas body mentah, jadi body harus diberikan ke `verify` sebelum di-parse sebagai JSON. Pakai contoh yang sesuai dengan framework HitungCuan:
202
+
203
+ | Framework | Contoh |
204
+ |---|---|
205
+ | Express | [`webhook.md` §5, Express](webhook.md#express) |
206
+ | NestJS | [`webhook.md` §5, NestJS](webhook.md#nestjs) |
207
+ | React Router atau server lain berbasis `Request` | [`webhook.md` §5, React Router](webhook.md#react-router-dan-server-berbasis-request) |
208
+
209
+ Ketiganya memanggil `handleWebhook` ([`webhook.md` §6](webhook.md#6-menangani-kiriman)): verifikasi, `saveOnce(tx, event)`, efek event, commit, lalu jawab `2xx`.
210
+
211
+ Untuk Express: `createApp(verifier, withTransaction, applyPaymentEvent).listen(port);`. `withTransaction` berasal dari lapisan database aplikasi ([`webhook.md` §7](webhook.md#7-dedup-di-transaksi-yang-sama)).
212
+
213
+ **Langkah 3. Tandai tagihan lunas di transaksi yang sama.** Efek event untuk HitungCuan:
214
+
215
+ <!-- snippet: examples/snippets/webhook-verifier.ts#apply-paid -->
216
+ ```ts
217
+ /** The payment id (`pay_…`) of a payments event, or null. */
218
+ function paymentId(event: VerifiedWebhook): string | null {
219
+ const subject = event.body.subject;
220
+ if (typeof subject !== "object" || subject === null || !("id" in subject)) return null;
221
+ return typeof subject.id === "string" ? subject.id : null;
222
+ }
223
+
224
+ /** Marks the bill paid from a verified payment.paid, in the transaction of saveOnce. Other types are only recorded. */
225
+ export const applyPaymentEvent: ApplyEvent = async (tx, event) => {
226
+ if (event.type !== "payment.paid") return;
227
+ const payment = paymentId(event);
228
+ if (payment === null) throw new Error(`payment.paid ${event.id} has no subject id`);
229
+ await tx.query("UPDATE bills SET status = 'paid', paid_at = now() WHERE payment_id = $1 AND status <> 'paid'", [payment]);
230
+ };
231
+ ```
232
+ <!-- /snippet -->
233
+
234
+ - Tagihan ditandai lunas hanya dari `payment.paid` yang lolos verifikasi. Halaman "berhasil" di browser bukan bukti pembayaran.
235
+ - `applyPaymentEvent` berjalan di transaksi database yang sama dengan `saveOnce(tx, event)`. Jawab `2xx` hanya setelah commit. Bila apa pun gagal, transaksi di-rollback dan route menjawab `5xx`, jadi Plasgos mengirim ulang dan event diproses saat itu ([`webhook.md` §7](webhook.md#7-dedup-di-transaksi-yang-sama)).
236
+ - Event lain (misalnya `payment.expired`) tetap dicatat oleh `saveOnce` dan dijawab `200`. Tambahkan cabangnya bila HitungCuan butuh.
237
+ - Sebagai cadangan, status payment bisa dibaca dengan `GET /v5/service/payments/{pay_id}` (scope `payments:read`).
238
+
239
+ **Rotasi secret.** Saat tim Plasgos menyerahkan secret webhook baru, segera pasang `PLASGOS_WEBHOOK_SECRET=baru,lama` dan deploy. Secret lama otomatis berhenti dipakai Plasgos 24 jam setelah rotasi, jadi HitungCuan harus sudah memakai secret baru sebelum itu. Setelah 24 jam, hapus secret lama. Rinciannya ada di [`webhook.md` §8](webhook.md#8-rotasi-secret).
240
+
241
+ Bila kiriman ditolak, arti setiap `reason` ada di [`error.md` §7](error.md#7-webhookverifyerror). Secret yang salah membuat setiap kiriman dijawab `401` dan menahan event berikutnya untuk payment yang sama. Setelah secret diperbaiki, minta tim Plasgos mengirim ulang.
242
+
243
+ ## 8. Sebelum production
244
+
245
+ - [ ] Cek koneksi (`/v5/service/me`) berhasil di sandbox.
246
+ - [ ] Payment sandbox berhasil dibuat dan dibayar, dan statusnya terbaca.
247
+ - [ ] Kredensial production berbeda dari sandbox dan tersimpan di secret manager.
248
+ - [ ] `PLASGOS_ENV=production`, `PLASGOS_ISSUER=https://accounts.plasgos.co.id`, `PLASGOS_API_URL=https://api.plasgos.co.id`.
249
+ - [ ] `onFailure` menulis ke log, dan `config_invalid` memicu alert.
250
+ - [ ] Webhook `payment.paid` sandbox diterima, lolos verifikasi, dan menandai tagihan lunas. Kiriman yang body-nya diubah dijawab `401` ([`webhook.md` §10](webhook.md#10-menguji-penerima)).
251
+ - [ ] Route webhook memakai body mentah dengan batas body, dan verifier dibuat saat start.
252
+ - [ ] `saveOnce` dan penandaan lunas berjalan di satu transaksi; `2xx` hanya setelah commit, `5xx` bila gagal.
253
+ - [ ] Route webhook menjawab dalam 10 detik.
254
+ - [ ] Secret webhook production berbeda dari sandbox dan tersimpan di secret manager.
255
+ - [ ] Tim yang men-deploy tahu langkah rotasi: pasang `baru,lama` segera, karena secret lama berhenti 24 jam setelah rotasi.
@@ -0,0 +1,244 @@
1
+ # Contoh: Plaslink (login seller, payments, webhook)
2
+
3
+ Plaslink memakai tiga hal dari Plasgos. Masing-masing punya kredensial sendiri dan bagian SDK sendiri:
4
+
5
+ | Kebutuhan | Kredensial | Bagian SDK | Status |
6
+ |---|---|---|---|
7
+ | Seller menghubungkan akun Plasgos ("Hubungkan Plasgos") | Client login (interaktif, pihak ketiga) | `createOidcClient` dari `@plasgos/oidc-client` | Panduan ini |
8
+ | Membuat payment | Client service app `plaslink` | `createServiceClient` dari `@plasgos/oidc-client/service` | Panduan ini |
9
+ | Menerima webhook payments dan pengiriman | Dua secret webhook | `createWebhookVerifier` dari `@plasgos/auth-verify/webhook` | Panduan ini |
10
+
11
+ Client login dan client service **bukan** client yang sama. Client id dan secret-nya berbeda, dan scope-nya tidak boleh tertukar ([`memulai.md` §3](memulai.md#3-dua-jenis-client)).
12
+
13
+ ## 1. Env
14
+
15
+ ```dotenv
16
+ PLASGOS_ENV=sandbox
17
+ PLASGOS_ISSUER=https://<host accounts sandbox>
18
+ PLASGOS_API_URL=https://api.sandbox.plasgos.co.id
19
+ APP_URL=https://<host plaslink>
20
+
21
+ # Client login (seller connect)
22
+ PLASGOS_LOGIN_CLIENT_ID=<client id login>
23
+ PLASGOS_LOGIN_CLIENT_SECRET=<client secret login>
24
+
25
+ # Client service (payments)
26
+ PLASGOS_SERVICE_CLIENT_ID=<client id service>
27
+ PLASGOS_SERVICE_CLIENT_SECRET=<client secret service>
28
+
29
+ # Cookie transaksi login
30
+ SESSION_SECRET=<acak, minimal 32 byte>
31
+
32
+ # Webhook: secret payments dan secret pengiriman berbeda
33
+ PLASGOS_WEBHOOK_SECRET=<secret webhook payments>
34
+ PLASGOS_SHIPPING_WEBHOOK_SECRET=<secret webhook pengiriman>
35
+ ```
36
+
37
+ Di production: `PLASGOS_ENV=production`, `PLASGOS_ISSUER=https://accounts.plasgos.co.id`, `PLASGOS_API_URL=https://api.plasgos.co.id`, dan kredensial production.
38
+
39
+ Redirect URI yang didaftarkan di Plasgos harus persis `<APP_URL>/auth/callback` (atau path lain yang Anda pilih, asalkan sama persis dengan `redirectUri`).
40
+
41
+ ## 2. Seller menghubungkan akun
42
+
43
+ ### Client login pihak ketiga
44
+
45
+ <!-- snippet: examples/snippets/login-client.ts#third-party -->
46
+ ```ts
47
+ /** An app outside Plasgos: identity only. No resource, no logout ticket. */
48
+ export function createThirdPartyClient(): OidcClient {
49
+ const env = readPlasgosEnv();
50
+ const credentials = readLoginCredentials();
51
+ return createOidcClient({
52
+ environment: env.environment,
53
+ issuer: env.issuer,
54
+ clientId: credentials.clientId,
55
+ clientSecret: credentials.clientSecret,
56
+ redirectUri: `${credentials.appUrl}/auth/callback`,
57
+ postLogoutRedirectUri: `${credentials.appUrl}/`,
58
+ scopes: ["openid", "profile", "email", "plaslink:shipping"],
59
+ profile: "third-party",
60
+ onFailure: logFailure,
61
+ });
62
+ }
63
+ ```
64
+ <!-- /snippet -->
65
+
66
+ Yang berbeda dari aplikasi Plasgos sendiri (`profile: "first-party"`):
67
+
68
+ | Hal | Client pihak ketiga |
69
+ |---|---|
70
+ | `resource` | Tidak boleh diisi. `ConfigError` bila diisi |
71
+ | Scope | `openid`, `profile`, `email`, `plaslink:shipping`. Scope first-party (`account:*`, `packages:*`, `plasgos:public_id`) ditolak saat start |
72
+ | Persetujuan | Seller selalu melihat halaman persetujuan Plasgos |
73
+ | Refresh token | Tidak ada, karena client tidak punya `offline_access` |
74
+ | Logout ticket | Tidak ada (`logoutTicket` tidak boleh `true`) |
75
+ | `backchannelUrl` | Tidak diisi. Plaslink berada di luar jaringan Plasgos |
76
+
77
+ `plaslink:shipping` adalah persetujuan seller agar Plaslink membuat pengiriman atas namanya.
78
+
79
+ ### Alurnya
80
+
81
+ Menghubungkan akun selalu berupa redirect satu halaman penuh ke Plasgos, lalu kembali ke Plaslink. Tidak ada popup atau iframe.
82
+
83
+ 1. Seller menekan "Hubungkan Plasgos". Plaslink memanggil `startLogin` dan menyimpan transaksi di cookie.
84
+ 2. Seller login dan menyetujui di Plasgos.
85
+ 3. Plasgos mengembalikan browser ke `/auth/callback`. Plaslink memanggil `handleCallback` dan mendapat identitas seller.
86
+
87
+ <!-- snippet: examples/snippets/plaslink-connect.ts#start -->
88
+ ```ts
89
+ /** GET /plasgos/connect: sends the seller to Plasgos to approve the connection. */
90
+ export function startConnect(client: OidcClient, store: SessionStore<AppSession>): Response {
91
+ const { location, transaction } = client.startLogin({ returnTo: "/settings/plasgos" });
92
+ return new Response(null, {
93
+ status: 302,
94
+ headers: {
95
+ Location: location,
96
+ "Set-Cookie": store.commitTransaction(transaction),
97
+ "Cache-Control": "no-store",
98
+ },
99
+ });
100
+ }
101
+ ```
102
+ <!-- /snippet -->
103
+
104
+ <!-- snippet: examples/snippets/plaslink-connect.ts#callback -->
105
+ ```ts
106
+ /** The Plasgos account a seller connected. `subject` is stable for this client and differs per client. */
107
+ export interface ConnectedSeller {
108
+ subject: string;
109
+ name: string | null;
110
+ email: string | null;
111
+ }
112
+
113
+ /**
114
+ * GET /auth/callback: returns the connected seller, or null when the connection failed.
115
+ * Append `setCookie` to the response either way: it clears the single-use transaction cookie.
116
+ */
117
+ export async function finishConnect(
118
+ client: OidcClient,
119
+ store: SessionStore<AppSession>,
120
+ request: Request,
121
+ ): Promise<{ seller: ConnectedSeller | null; setCookie: string }> {
122
+ const setCookie = store.clearTransaction();
123
+ try {
124
+ const { claims } = await client.handleCallback(request.url, store.readTransaction(request));
125
+ return { seller: { subject: claims.sub, name: claims.name ?? null, email: claims.email ?? null }, setCookie };
126
+ } catch (error) {
127
+ if (!(error instanceof OidcError)) throw error;
128
+ return { seller: null, setCookie };
129
+ }
130
+ }
131
+ ```
132
+ <!-- /snippet -->
133
+
134
+ `store` adalah session store dari `@plasgos/oidc-client/session`. Di sini ia hanya dipakai untuk cookie transaksi (berumur 10 menit). Cara membuatnya ada di [`login-web.md`](login-web.md). File lengkap contoh ini: [`plaslink-connect.ts`](examples/plaslink-connect.ts).
135
+
136
+ ### Yang disimpan Plaslink
137
+
138
+ Simpan `seller.subject` di data seller Plaslink. Itulah identitas akun Plasgos yang terhubung.
139
+
140
+ - `subject` adalah `sub` pairwise: tetap sama untuk seller itu di client Plaslink, dan berbeda dari `sub` seller yang sama di aplikasi lain. Bila seller memutus lalu menghubungkan lagi, `sub`-nya tetap sama.
141
+ - Plaslink tidak perlu menyimpan access token Plasgos. Sesi login Plaslink tetap milik Plaslink.
142
+ - Token Plasgos tidak membawa role atau tim. Hak akses di Plaslink diatur Plaslink.
143
+
144
+ Untuk memanggil API pengiriman (`/v5/plaslink/*`), Plaslink mengirim `sub` itu di header `X-Plasgos-Subject`, dengan Basic auth memakai kredensial client login. Panggilan itu di luar cakupan SDK ini. Kontraknya ada di dokumentasi API Plaslink shipping milik Plasgos.
145
+
146
+ Bila `finishConnect` mengembalikan `seller: null`, tampilkan pesan gagal dan tawarkan untuk mencoba lagi. Penyebabnya tercatat lewat `onFailure`. Arti setiap `reason` ada di [`error.md`](error.md).
147
+
148
+ ## 3. Payments
149
+
150
+ Payments memakai client service app `plaslink`, sama persis dengan [`server-ke-server.md`](server-ke-server.md):
151
+
152
+ <!-- snippet: examples/snippets/service-client.ts#create -->
153
+ ```ts
154
+ /** Create it once at start and reuse it: the token cache lives in the client. */
155
+ export function createPlasgosClient(): ServiceClient {
156
+ const env = readPlasgosEnv();
157
+ const credentials = readServiceCredentials();
158
+ return createServiceClient({
159
+ environment: env.environment,
160
+ issuer: env.issuer,
161
+ apiUrl: env.apiUrl,
162
+ backchannelUrl: env.backchannelUrl,
163
+ clientId: credentials.clientId,
164
+ clientSecret: credentials.clientSecret,
165
+ scopes: ["platform:self.read", "payments:read", "payments:write"],
166
+ resource: credentials.audience,
167
+ onFailure: logFailure,
168
+ });
169
+ }
170
+ ```
171
+ <!-- /snippet -->
172
+
173
+ Sesuaikan `scopes` dengan yang dimiliki client service Plaslink. Tambahkan `payments:refund` bila Plaslink melakukan refund lewat API.
174
+
175
+ Membuat payment, cek koneksi, refund, dan penanganan kegagalan: lihat [`server-ke-server.md` §4–§7](server-ke-server.md#4-fetch-memanggil-api).
176
+
177
+ ## 4. Webhook
178
+
179
+ Plaslink menerima dua jenis webhook: event payments dan event pengiriman. Masing-masing punya header dan secret sendiri, jadi Plaslink memakai dua verifier. Aturan lengkapnya ada di [`webhook.md`](webhook.md).
180
+
181
+ Install `@plasgos/auth-verify` di samping `@plasgos/oidc-client`, dengan nomor versi persis yang sama (`pnpm add @plasgos/auth-verify@<versi> --save-exact`). Salin `webhook-verifier.ts` dari [folder contoh](examples/).
182
+
183
+ | Jenis | Preset | Secret (env) | Header tanda tangan |
184
+ |---|---|---|---|
185
+ | Payments | `presets.payments` | `PLASGOS_WEBHOOK_SECRET` | `X-Signature` |
186
+ | Pengiriman | `presets.plaslinkShipping` | `PLASGOS_SHIPPING_WEBHOOK_SECRET` | `X-Plasgos-Signature` |
187
+
188
+ ### Dua verifier
189
+
190
+ Buat keduanya saat start:
191
+
192
+ <!-- snippet: examples/snippets/webhook-verifier.ts#create -->
193
+ ```ts
194
+ /** Payments webhooks. Create it once at start: a wrong option throws one ConfigError there. */
195
+ export function createPaymentsWebhookVerifier(): WebhookVerifier {
196
+ return createWebhookVerifier({
197
+ environment: readEnvironment(),
198
+ secrets: readWebhookSecrets("PLASGOS_WEBHOOK_SECRET"),
199
+ preset: presets.payments,
200
+ });
201
+ }
202
+ ```
203
+ <!-- /snippet -->
204
+
205
+ <!-- snippet: examples/snippets/webhook-verifier.ts#create-shipping -->
206
+ ```ts
207
+ /** Plaslink shipping webhooks: other header names and a secret of their own. */
208
+ export function createShippingWebhookVerifier(): WebhookVerifier {
209
+ return createWebhookVerifier({
210
+ environment: readEnvironment(),
211
+ secrets: readWebhookSecrets("PLASGOS_SHIPPING_WEBHOOK_SECRET"),
212
+ preset: presets.plaslinkShipping,
213
+ });
214
+ }
215
+ ```
216
+ <!-- /snippet -->
217
+
218
+ Di file start aplikasi: `const paymentsVerifier = createOrExit(createPaymentsWebhookVerifier);` dan `const shippingVerifier = createOrExit(createShippingWebhookVerifier);`.
219
+
220
+ ### Route
221
+
222
+ Paling sederhana: dua route, satu per jenis, misalnya `/webhooks/plasgos/payments` dengan `paymentsVerifier` dan `/webhooks/plasgos/shipping` dengan `shippingVerifier`. Setiap route menerima body mentah dan memanggil `handleWebhook` ([`webhook.md` §5](webhook.md#5-body-mentah-per-framework) dan [§6](webhook.md#6-menangani-kiriman)).
223
+
224
+ Bila hanya ada satu URL, pilih verifier dari keluarga header: kiriman pengiriman membawa `X-Plasgos-Signature`, kiriman payments membawa `X-Signature`. Verifier yang salah menolak kiriman dengan `missing_header`.
225
+
226
+ ### Dedup
227
+
228
+ `saveOnce(tx, event)` berjalan di transaksi database yang sama dengan efek event. Jawab `2xx` hanya setelah commit. Bila apa pun gagal, rollback dan jawab `5xx`, jadi Plasgos mengirim ulang dan event diproses saat itu ([`webhook.md` §7](webhook.md#7-dedup-di-transaksi-yang-sama)).
229
+
230
+ **Event pengiriman yang tampil degraded.** Plaslink juga membaca event pengiriman lewat endpoint fakta (`GET /v5/plaslink/shipping/shipments/{plaslink_order_id}/events`). Di sana sebuah event bisa tampil degraded (`data: null`, `render_error: true`), dan Plaslink menandainya dilewati. Bila webhook untuk id event yang sama datang belakangan, event itu **bukan** duplikat: proses seperti biasa. Karena itu:
231
+
232
+ - pakai tabel dedup webhook yang terpisah dari catatan endpoint fakta, atau
233
+ - anggap baris yang degraded sebagai belum tersimpan, sehingga `saveOnce` mengembalikan `true` untuk webhook-nya.
234
+
235
+ Event payments dan event pengiriman memakai id yang berbeda. Satu tabel dedup untuk keduanya boleh, asalkan aturan degraded di atas tetap berlaku.
236
+
237
+ ### Rotasi secret
238
+
239
+ - **Payments:** saat tim Plasgos menyerahkan secret baru, segera pasang `PLASGOS_WEBHOOK_SECRET=baru,lama` dan deploy. Secret lama otomatis berhenti dipakai Plasgos 24 jam setelah rotasi, jadi Plaslink harus sudah memakai secret baru sebelum itu.
240
+ - **Pengiriman:** pasang `PLASGOS_SHIPPING_WEBHOOK_SECRET=baru,lama`, deploy, lalu konfirmasi ke tim Plasgos. Tim Plasgos baru menghentikan secret lama setelah konfirmasi Plaslink.
241
+
242
+ Setelah secret lama berhenti, hapus dari env. Rinciannya ada di [`webhook.md` §8](webhook.md#8-rotasi-secret).
243
+
244
+ Bila kiriman ditolak, arti setiap `reason` ada di [`error.md` §7](error.md#7-webhookverifyerror). Secret yang salah membuat setiap kiriman dijawab `401` dan menahan event berikutnya untuk payment atau pengiriman yang sama. Setelah secret diperbaiki, minta tim Plasgos mengirim ulang.