@plasgos/auth-verify 0.0.0-stage → 0.1.0-next.3
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.
- package/CHANGELOG.md +27 -0
- package/LICENSE +15 -0
- package/README.md +122 -2
- package/THIRD_PARTY_NOTICES.md +31 -0
- package/dist/express.cjs +157 -0
- package/dist/express.cjs.map +1 -0
- package/dist/express.d.cts +90 -0
- package/dist/express.d.ts +90 -0
- package/dist/express.js +127 -0
- package/dist/express.js.map +1 -0
- package/dist/index.cjs +1254 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +67 -0
- package/dist/index.d.ts +67 -0
- package/dist/index.js +499 -0
- package/dist/index.js.map +1 -0
- package/dist/nestjs.cjs +1395 -0
- package/dist/nestjs.cjs.map +1 -0
- package/dist/nestjs.d.cts +153 -0
- package/dist/nestjs.d.ts +153 -0
- package/dist/nestjs.js +637 -0
- package/dist/nestjs.js.map +1 -0
- package/dist/types-CGtRnj59.d.cts +193 -0
- package/dist/types-CGtRnj59.d.ts +193 -0
- package/dist/webhook.cjs +296 -0
- package/dist/webhook.cjs.map +1 -0
- package/dist/webhook.d.cts +196 -0
- package/dist/webhook.d.ts +196 -0
- package/dist/webhook.js +265 -0
- package/dist/webhook.js.map +1 -0
- package/docs/bff-express.md +1314 -0
- package/docs/consumers.md +98 -0
- package/docs/contoh-hitungcuan.md +255 -0
- package/docs/contoh-plaslink.md +244 -0
- package/docs/error.md +613 -0
- package/docs/examples/auth-verify-readme.ts +42 -0
- package/docs/examples/bff-express.ts +370 -0
- package/docs/examples/bff-proxy.ts +335 -0
- package/docs/examples/bff-redis-lock.ts +187 -0
- package/docs/examples/bff-revocation.ts +136 -0
- package/docs/examples/config-error.ts +24 -0
- package/docs/examples/env.ts +150 -0
- package/docs/examples/failure-log.ts +18 -0
- package/docs/examples/login-client.ts +46 -0
- package/docs/examples/login-flow.ts +186 -0
- package/docs/examples/plaslink-connect.ts +48 -0
- package/docs/examples/readme.ts +60 -0
- package/docs/examples/service-client.ts +105 -0
- package/docs/examples/session-store.ts +53 -0
- package/docs/examples/token-commonjs.cjs +95 -0
- package/docs/examples/token-express.ts +56 -0
- package/docs/examples/token-fetch.ts +24 -0
- package/docs/examples/token-nestjs-jest.ts +77 -0
- package/docs/examples/token-nestjs.ts +127 -0
- package/docs/examples/token-socket.ts +59 -0
- package/docs/examples/token-testing.ts +100 -0
- package/docs/examples/token-verifier.ts +132 -0
- package/docs/examples/user-events.ts +110 -0
- package/docs/examples/webhook-express.ts +46 -0
- package/docs/examples/webhook-fetch.ts +60 -0
- package/docs/examples/webhook-nestjs.ts +59 -0
- package/docs/examples/webhook-testing.ts +60 -0
- package/docs/examples/webhook-verifier.ts +197 -0
- package/docs/login-web.md +650 -0
- package/docs/memulai.md +419 -0
- package/docs/server-ke-server.md +287 -0
- package/docs/verifikasi-token.md +1219 -0
- package/docs/webhook.md +810 -0
- package/package.json +101 -3
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# Install paket `@plasgos/*`
|
|
2
|
+
|
|
3
|
+
Panduan ini untuk aplikasi yang memakai paket `@plasgos/oidc-client` atau `@plasgos/auth-verify`. Isinya: cara install di laptop, di Docker, dan di CI, aturan versi, dan lisensi.
|
|
4
|
+
|
|
5
|
+
Paket diterbitkan di npmjs.com (`registry.npmjs.org`) sebagai paket **publik** di scope `@plasgos`, sama seperti paket `@plasgos/*` lain (misalnya `@plasgos/webchat`). Install tidak butuh token, `.npmrc` khusus, atau secret. Repo sumbernya privat; yang publik hanya paket hasil build. Panduan pemakaian ikut di dalam paket `@plasgos/oidc-client` dan `@plasgos/auth-verify` (isinya sama), di folder `docs/`: bisa dibaca di tab **Code** halaman paket di npmjs.com, atau di `node_modules/@plasgos/oidc-client/docs/` atau `node_modules/@plasgos/auth-verify/docs/` setelah install.
|
|
6
|
+
|
|
7
|
+
Status saat ini: `@plasgos/auth-shared`, `@plasgos/oidc-client`, dan `@plasgos/auth-verify` terbit di npmjs.com sebagai pre-release, selalu dengan nomor versi yang sama. Cek versi yang ada dengan `npm view @plasgos/auth-verify versions`.
|
|
8
|
+
|
|
9
|
+
Setelah paket terpasang, lanjut ke [`memulai.md`](memulai.md).
|
|
10
|
+
|
|
11
|
+
## 1. Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pnpm add @plasgos/oidc-client@<versi> --save-exact
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Aplikasi yang menerima webhook dari Plasgos atau memeriksa access token Plasgos di API-nya sendiri meng-install `@plasgos/auth-verify`, sendiri atau di samping `@plasgos/oidc-client`, dengan versi yang sama:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pnpm add @plasgos/auth-verify@<versi> --save-exact
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Ganti `<versi>` dengan nomor versi persis (lihat §5). `@plasgos/auth-shared` ikut terpasang dengan versi yang sama, jadi tidak perlu di-install sendiri.
|
|
24
|
+
|
|
25
|
+
Perintah ini sama di laptop, di Docker, dan di CI. Tidak ada token yang perlu dibuat atau diatur.
|
|
26
|
+
|
|
27
|
+
### Node, CommonJS, dan NestJS
|
|
28
|
+
|
|
29
|
+
- Paket butuh Node `>=22.22` (`engines`). Image Docker aplikasi juga harus memakai Node 22.22 atau lebih baru; tag `node:22-slim` atau `node:22-alpine` yang lama bisa masih di bawah itu, jadi cek dengan `docker run --rm <image> node --version`.
|
|
30
|
+
- Setiap paket punya build ESM dan CommonJS. Aplikasi CommonJS (tanpa `"type": "module"`, memakai `require`) dan test di Jest (dengan ts-jest) memakai build CommonJS tanpa flag atau pengaturan tambahan: tidak perlu `--experimental-vm-modules`, `transformIgnorePatterns`, atau `require(esm)`.
|
|
31
|
+
- `@plasgos/auth-verify` memakai `jose` untuk memeriksa tanda tangan token. Build ESM meng-import `jose` dari `node_modules`; build CommonJS (`.` dan `/nestjs`) membawa salinan `jose` sendiri di dalamnya, karena `jose` hanya tersedia sebagai ESM. Lisensi salinan itu ada di `THIRD_PARTY_NOTICES.md` di dalam paket.
|
|
32
|
+
- Akibatnya, `overrides` untuk `jose` (pnpm atau npm) hanya mengganti `jose` yang dipakai build ESM, bukan salinan di build CommonJS. Bila ada perbaikan keamanan `jose`, tim Plasgos merilis patch `@plasgos/auth-verify` dengan `jose` yang sudah diperbaiki; naikkan versi `@plasgos/auth-verify`, jangan hanya meng-override `jose`.
|
|
33
|
+
- `@plasgos/auth-verify/nestjs` memakai `@nestjs/common` dan `@nestjs/core` versi 11 (`^11.0.0`) milik aplikasi. Keduanya peer dependency opsional: aplikasi yang tidak memakai `/nestjs` tidak perlu meng-install NestJS, dan `/express` tidak butuh paket `express` sebagai dependensi. NestJS 12 belum didukung.
|
|
34
|
+
|
|
35
|
+
## 2. `.npmrc` di repo aplikasi
|
|
36
|
+
|
|
37
|
+
Tidak perlu baris apa pun untuk `@plasgos`. Paket diambil dari registry bawaan (`registry.npmjs.org`).
|
|
38
|
+
|
|
39
|
+
Bila `.npmrc` aplikasi masih punya baris yang mengarahkan `@plasgos` ke GitHub Packages, hapus baris itu beserta baris token-nya:
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
@plasgos:registry=https://npm.pkg.github.com
|
|
43
|
+
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Satu scope hanya bisa diarahkan ke satu registry. Selama baris pertama masih ada, semua paket `@plasgos/*` dicari di GitHub Packages dan install gagal. Baris lain di `.npmrc` (misalnya `save-exact=true`) tetap dipakai.
|
|
47
|
+
|
|
48
|
+
## 3. Dockerfile
|
|
49
|
+
|
|
50
|
+
Install di Docker cukup `pnpm install` biasa. Tidak ada BuildKit secret, `--mount=type=secret`, `ARG`, atau `ENV` untuk token.
|
|
51
|
+
|
|
52
|
+
```dockerfile
|
|
53
|
+
FROM node:26-trixie-slim AS deps
|
|
54
|
+
WORKDIR /app
|
|
55
|
+
COPY package.json pnpm-lock.yaml ./
|
|
56
|
+
# Node 26 tidak lagi membawa corepack, jadi pnpm dipasang lewat npm (versi dari `packageManager`).
|
|
57
|
+
RUN npm install -g --no-fund --no-audit "$(node -p 'require("./package.json").packageManager')"
|
|
58
|
+
RUN pnpm install --frozen-lockfile
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Build-nya:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
docker build -t app .
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Aturan:
|
|
68
|
+
|
|
69
|
+
- Stage `runtime` hanya mengambil `node_modules`, hasil build, dan file yang dibutuhkan saat aplikasi berjalan. Stage itu tidak meng-copy `.npmrc`.
|
|
70
|
+
- Bila Dockerfile aplikasi masih memakai `--mount=type=secret,id=npm_token,…` hanya untuk `@plasgos/*`, mount itu boleh dihapus, begitu juga `--secret id=npm_token,…` di perintah `docker build`.
|
|
71
|
+
|
|
72
|
+
## 4. CI
|
|
73
|
+
|
|
74
|
+
GitLab CI dan GitHub Actions menjalankan `pnpm install` atau `docker build` seperti biasa, tanpa variable atau secret untuk paket ini.
|
|
75
|
+
|
|
76
|
+
Bila project GitLab aplikasi punya variable `NPM_TOKEN` yang hanya dipakai untuk `@plasgos/*` dari GitHub Packages, variable itu tidak dipakai lagi dan boleh dihapus. Bila workflow GitHub Actions aplikasi memberi `packages: read` dan meneruskan `GITHUB_TOKEN` hanya untuk paket ini, keduanya juga boleh dihapus.
|
|
77
|
+
|
|
78
|
+
## 5. Versi
|
|
79
|
+
|
|
80
|
+
- Selama versi masih `0.x`, tulis rentang `~0.y.z` di `package.json` aplikasi. Di `0.x`, kenaikan minor dianggap breaking, jadi aplikasi hanya menerima patch secara otomatis. `pnpm add` tidak menulis rentang ini (ia menulis versi persis bila `save-exact=true`, selain itu `^`), jadi ubah rentangnya dengan tangan setelah `pnpm add`.
|
|
81
|
+
- Setelah `1.0.0`, pakai rentang `^`.
|
|
82
|
+
- Versi yang benar-benar terpasang ditentukan lockfile aplikasi. Menaikkan versi berarti membuat PR di repo aplikasi, supaya test aplikasi ikut berjalan.
|
|
83
|
+
- Semua paket `@plasgos/*` di SDK ini dirilis dengan nomor versi yang sama. Aplikasi yang memakai dua paket menaikkan keduanya sekaligus.
|
|
84
|
+
- `@plasgos/auth-shared` tidak di-install langsung. Paket itu ikut terpasang sebagai dependensi `oidc-client` dan `auth-verify`.
|
|
85
|
+
|
|
86
|
+
**Pre-release `next`.** Versi uji terbit sebagai `x.y.z-next.n`. Pre-release hanya di-install dengan nomor versi persis (§1), yang diambil dari halaman paket di npmjs.com atau `CHANGELOG.md` paket. Dist-tag `next` tidak dijamin menunjuk ke versi uji terbaru, jadi jangan meng-install dengan `@next`.
|
|
87
|
+
|
|
88
|
+
Rentang `~0.y.z` tidak pernah cocok dengan pre-release. Sampai rilis stabil pertama terbit, `pnpm add @plasgos/oidc-client` tanpa nomor versi gagal (tidak ada versi di dist-tag `latest`) atau mendapat sebuah pre-release yang tidak Anda pilih. Karena itu selalu install dengan nomor versi persis.
|
|
89
|
+
|
|
90
|
+
Perintah di §1 menulis versi persis (`x.y.z-next.n`) ke `package.json`, dan versi persis tidak pernah pindah sendiri. Bila yang tertulis adalah rentang `^` atau `~` pada pre-release, rentang itu juga menerima rilis stabil di minor yang sama, tetapi lockfile menahan pre-release itu sampai aplikasi menjalankan `pnpm update`. Setelah rilis stabil terbit, ubah versinya menjadi `~0.y.z` lewat PR.
|
|
91
|
+
|
|
92
|
+
**Perbaikan keamanan.** Perbaikan dirilis sebagai patch, dan tim Plasgos memberi tahu tim aplikasi yang memakai paket ini. Naikkan versi, perbarui lockfile, dan deploy secepatnya. Versi yang bermasalah di-deprecate (`npm deprecate`), tidak dihapus, supaya lockfile lama tetap bisa di-install sampai aplikasinya naik versi.
|
|
93
|
+
|
|
94
|
+
## 6. Isi paket dan lisensi
|
|
95
|
+
|
|
96
|
+
- Paket berisi `dist` (ESM, CJS, `.d.ts`, dan source map), `README.md`, `CHANGELOG.md`, dan `LICENSE`. `@plasgos/auth-verify` juga membawa `THIRD_PARTY_NOTICES.md`, lisensi `jose` yang ada di dalam build CommonJS-nya. `@plasgos/oidc-client` dan `@plasgos/auth-verify` juga membawa folder `docs/` dengan isi yang sama: panduan ini dan file contohnya (`docs/examples/`).
|
|
97
|
+
- Source map ikut terbit lengkap dengan `sourcesContent`, supaya stack trace menunjuk ke sumber TypeScript. Karena paketnya publik, sumber TypeScript paket ikut terbaca siapa pun yang mengunduh paket. Ini disengaja.
|
|
98
|
+
- Lisensi: bukan open source. Paket milik Plasgos dan hanya boleh dipakai untuk menghubungkan aplikasi ke layanan Plasgos (login dan API Plasgos) oleh pemegang kredensial client resmi dari Plasgos dan pengembang yang bekerja untuk mereka. Menyalin, mengubah, menerbitkan ulang, atau mendistribusikan paket tanpa izin tertulis Plasgos dilarang. Teks lengkapnya ada di file [`LICENSE`](../LICENSE) di setiap paket.
|
|
@@ -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.
|