StokAPI — API Stok & Harga untuk Integrasi

Buat struktur proyek Node.js dengan Fastify, Prisma, dan PostgreSQL. Konfigurasi Vitest sebagai test runner. Pastikan ada file `src/server.ts` untuk Fastify app, `prisma/schema.prisma` untuk skema database, dan `vitest.config.ts`.

Buat file `prisma/schema.prisma` dengan definisi tabel `products`, `stocks`, `api_keys`, `webhook_subscriptions`, dan `webhook_events` sesuai `databaseSchema` di PRD. Terapkan relasi dan constraint yang diperlukan. Jalankan `prisma migrate dev` untuk membuat migrasi awal.

Buat file `src/repositories/product.repository.ts` yang mengimplementasikan fungsi CRUD dasar untuk entitas `Product` menggunakan Prisma Client. Sertakan fungsi `findMany`, `findBySku`, `updatePrice`.

Buat file `src/repositories/stock.repository.ts` yang mengimplementasikan fungsi untuk `findByProductId`, `updateQuantity` (dengan penambahan/pengurangan) menggunakan Prisma Client. Pastikan operasi update kuantitas aman dari race condition dengan `UPDATE ... SET quantity = quantity + X WHERE ...`.

Buat file `src/repositories/api-key.repository.ts` yang mengimplementasikan fungsi `findByKeyHash`, `create`, `updateStatus`, dan `recordUsage` untuk entitas `ApiKey` menggunakan Prisma Client.

Buat file `src/repositories/webhook.repository.ts` yang mengimplementasikan fungsi `findSubscriptionsByEvent`, `createSubscription`, `createEvent`, `updateEventStatus` untuk entitas `WebhookSubscription` dan `WebhookEvent` menggunakan Prisma Client.

Buat file `src/services/auth.service.ts` yang berisi fungsi `validateApiKey(key: string)` yang mencari API key di database, memverifikasi keaktifannya, dan mencatat penggunaan. Implementasikan juga logika rate limiting menggunakan in-memory store (misal: `lru-cache` atau `rate-limiter-flexible`) per API key. Jika rate limit terlampaui, throw error `RATE_LIMIT_EXCEEDED`.

Buat file `src/plugins/auth.plugin.ts` sebagai plugin Fastify. Plugin ini harus mengekstrak `X-API-Key` dari header, memanggil `auth.service.ts#validateApiKey`, dan jika valid, mendekorasi request dengan objek `apiKey` yang ditemukan. Jika tidak valid atau rate limit terlampaui, kirim respons error 401/429 dengan format error seragam.

Buat file `src/routes/v1/products.routes.ts` yang berisi endpoint `GET /v1/products`. Terapkan middleware otentikasi. Endpoint ini harus menerima query params `page`, `limit`, `search` (untuk nama/SKU), `sortBy`, `sortOrder`. Panggil `product.repository.ts#findMany` dan kembalikan respons paginasi.

Tambahkan endpoint `GET /v1/products/:sku` ke `src/routes/v1/products.routes.ts`. Terapkan middleware otentikasi. Endpoint ini harus memanggil `product.repository.ts#findBySku`. Jika produk tidak ditemukan, kembalikan error 404 `PRODUCT_NOT_FOUND`.

Tambahkan endpoint `PATCH /v1/products/:sku/stock` ke `src/routes/v1/products.routes.ts`. Terapkan middleware otentikasi. Endpoint ini harus menerima body `{ quantity_change: number }`. Panggil `stock.repository.ts#updateQuantity`. Jika stok menjadi negatif, kembalikan error 400 `INSUFFICIENT_STOCK`. Tangani race condition dengan update atomik di database.

Tambahkan endpoint `PATCH /v1/products/:sku/price` ke `src/routes/v1/products.routes.ts`. Terapkan middleware otentikasi. Endpoint ini harus menerima body `{ price?: number, hpp?: number }`. Panggil `product.repository.ts#updatePrice`. Pastikan harga dan HPP tidak boleh negatif.

Buat file `src/services/webhook.service.ts`. Implementasikan fungsi `sendWebhook(subscription: WebhookSubscription, eventPayload: object)` yang menggunakan `axios` untuk mengirim POST request. Jika gagal, simpan event ke `webhook_events` dengan status `PENDING` dan jadwalkan percobaan ulang. Buat juga fungsi `processPendingWebhooks()` yang akan dipanggil oleh background job.

Modifikasi `src/services/product.service.ts` dan `src/services/stock.service.ts` (jika ada, atau langsung di route handler) untuk memanggil `webhook.service.ts#sendWebhook` setelah update stok atau harga. Untuk stok, cek apakah kuantitas baru di bawah ambang batas (misal: 5). Untuk harga, selalu kirim notifikasi jika berubah. Ambil ambang batas stok dari `products.low_stock_threshold`.

Buat file `src/jobs/webhook-retry.job.ts`. Job ini harus memanggil `webhook.service.ts#processPendingWebhooks()`. Konfigurasi job ini agar berjalan setiap 5 menit menggunakan `node-cron` atau library serupa. Pastikan job ini diinisialisasi di `src/server.ts`.

Modifikasi `src/server.ts` untuk menambahkan `setErrorHandler` Fastify. Handler ini harus menangkap semua error yang dilempar oleh route/service dan mengubahnya menjadi format JSON `{ success: false, message: string, code?: string }` dengan kode status HTTP yang sesuai (400, 401, 404, 429, 500). Definisikan custom error class untuk error domain seperti `ProductNotFound`, `InsufficientStock`, `InvalidApiKey`, `RateLimitExceeded`.

Instal `fastify-swagger` dan `swagger-ui-dist`. Konfigurasi plugin di `src/server.ts` untuk melayani dokumentasi di `/api-docs`. Tambahkan skema OpenAPI (menggunakan JSDoc atau skema JSON/YAML) untuk semua endpoint di `src/routes/v1/products.routes.ts`, termasuk parameter, body request, respons sukses, dan respons error seragam. Sertakan contoh cURL untuk setiap endpoint.

Buat endpoint `POST /v1/api-keys` di `src/routes/v1/api-keys.routes.ts`. Endpoint ini harus menerima body `{ client_name: string, rate_limit_per_minute: number }`. Hasilkan API key (string acak), hash menggunakan bcrypt, simpan hash ke database, dan kembalikan API key mentah HANYA SEKALI di respons. Endpoint ini harus dilindungi oleh API key khusus 'master' atau diakses secara manual.

Tambahkan endpoint `PATCH /v1/api-keys/:id` ke `src/routes/v1/api-keys.routes.ts`. Endpoint ini harus menerima body `{ is_active?: boolean, rate_limit_per_minute?: number }`. Hanya API key master yang boleh mengakses endpoint ini. Panggil `api-key.repository.ts#update`.

Buat endpoint `POST /v1/webhook-subscriptions` di `src/routes/v1/webhook-subscriptions.routes.ts`. Endpoint ini harus menerima body `{ event_type: 'low_stock' | 'price_change', callback_url: string }`. Panggil `webhook.repository.ts#createSubscription`. Pastikan `callback_url` adalah URL yang valid.