kiriminaja 0.1.4 → 0.1.6

package/README.md

@@ -4,31 +4,26 @@
 [![npm downloads](https://img.shields.io/npm/dw/kiriminaja)](https://www.npmjs.com/package/kiriminaja)
 [![license](https://img.shields.io/github/license/kiriminaja/node)](LICENSE)
 
+Framework-agnostic JavaScript/TypeScript SDK for the [KiriminAja](https://kiriminaja.com) logistics API. Works with Node.js, Bun, Deno, and any runtime that supports the Fetch API — including Nuxt/Nitro via the included h3 adapter.
+
 ## Requirements
 
-- Node.js 18+ (has built-in `fetch`), or provide `fetch` via `KiriminAja.init({ fetch })`
+- Node.js 18+, Bun, or Deno (built-in `fetch`); or pass a custom `fetch` via `KiriminAja.init({ fetch })`
 
 ## Installation
 
 ```bash
 npm install kiriminaja
+# yarn add kiriminaja
+# pnpm add kiriminaja
+# bun add kiriminaja
 ```
 
-```bash
-yarn add kiriminaja
-```
-
-```bash
-pnpm add kiriminaja
-```
-
-```bash
-bun add kiriminaja
-```
+---
 
-## Setup
+## Quick Start
 
-Initialize once, then use any endpoint.
+Call `KiriminAja.init()` once at app startup, then call any service method anywhere.
 
 ```ts
 import KiriminAja, { KAEnv } from "kiriminaja";
@@ -37,56 +32,233 @@ KiriminAja.init({
     env: KAEnv.SANDBOX, // or KAEnv.PRODUCTION
     apiKey: process.env.KIRIMINAJA_API_KEY,
 });
+
+// Use any service
+const provinces = await KiriminAja.address.provinces();
 ```
 
-If you need to override the base URL:
+---
+
+## Init Options
+
+| Option    | Type        | Default            | Description                           |
+| --------- | ----------- | ------------------ | ------------------------------------- |
+| `env`     | `KAEnv`     | `KAEnv.SANDBOX`    | Target environment                    |
+| `apiKey`  | `string`    | —                  | Your KiriminAja API key               |
+| `baseUrl` | `string`    | Derived from `env` | Override the base URL                 |
+| `fetch`   | `FetchLike` | `globalThis.fetch` | Custom fetch (polyfill / test mock)   |
+| `headers` | `object`    | —                  | Extra headers sent with every request |
 
 ```ts
+// Custom base URL
 KiriminAja.init({
     baseUrl: "https://tdev.kiriminaja.com",
     apiKey: process.env.KIRIMINAJA_API_KEY,
 });
+
+// Node.js < 18 — bring your own fetch
+import fetch from "node-fetch";
+KiriminAja.init({ apiKey: "...", fetch });
 ```
 
-If you are on Node.js < 18, pass a `fetch` implementation:
+---
+
+## Services
+
+### Address
 
 ```ts
-import KiriminAja from "kiriminaja";
+// List all provinces
+await KiriminAja.address.provinces();
 
-KiriminAja.init({
-    apiKey: process.env.KIRIMINAJA_API_KEY,
-    fetch, // provide your own fetch polyfill
+// Cities in a province (provinsi_id)
+await KiriminAja.address.cities(5);
+
+// Districts in a city (kabupaten_id)
+await KiriminAja.address.districts(12);
+
+// Sub-districts in a district (kecamatan_id)
+await KiriminAja.address.subDistricts(77);
+
+// Search districts by name
+await KiriminAja.address.districtsByName("jakarta");
+```
+
+---
+
+### Coverage Area & Pricing
+
+```ts
+// Express shipping rates
+await KiriminAja.coverageArea.pricingExpress({
+    origin: 1,
+    destination: 2,
+    weight: 1000, // grams
+    item_value: 50000,
+    insurance: 0,
+    courier: ["jne", "jnt"],
+});
+
+// Instant (same-day) rates
+await KiriminAja.coverageArea.pricingInstant({
+    service: ["instant"],
+    item_price: 10000,
+    origin: { lat: -6.2, long: 106.8, address: "Jl. Sudirman No.1" },
+    destination: { lat: -6.21, long: 106.81, address: "Jl. Thamrin No.5" },
+    weight: 1000,
+    vehicle: "bike",
+    timezone: "Asia/Jakarta",
 });
 ```
 
-## Usage
+---
 
-Coverage area:
+### Order — Express
 
 ```ts
-const provinces = await KiriminAja.address.provinces();
-const cities = await KiriminAja.address.cities(5);
+// Track by AWB
+await KiriminAja.order.express.track("AWB123456");
+
+// Cancel
+await KiriminAja.order.express.cancel("AWB123456", "Customer request");
+
+// Request pickup (v5)
+await KiriminAja.order.express.requestPickupV5(payload);
+
+// Request pickup (v6.1)
+await KiriminAja.order.express.requestPickupV61(payload);
 ```
 
-Order:
+---
+
+### Order — Instant
 
 ```ts
-const tracking = await KiriminAja.order.express.track("ORDER_ID");
-const instantTracking = await KiriminAja.order.instant.track("ORDER_ID");
+// Create instant pickup
+await KiriminAja.order.instant.create(payload);
+
+// Find a new driver for an existing order
+await KiriminAja.order.instant.findNewDriver(orderId);
+
+// Cancel instant order
+await KiriminAja.order.instant.cancel(orderId);
+
+// Track instant order
+await KiriminAja.order.instant.track(orderId);
 ```
 
-## Development
+---
 
-To install dependencies:
+### Courier
 
-```bash
-bun install
+```ts
+// List available couriers
+await KiriminAja.courier.list();
+
+// Courier groups
+await KiriminAja.courier.group();
+
+// Courier detail
+await KiriminAja.courier.detail(courierId);
+
+// Update whitelist services
+await KiriminAja.courier.setWhitelistServices(payload);
 ```
 
-To run:
+---
 
-```bash
-bun run index.ts
+### Pickup Schedules
+
+```ts
+await KiriminAja.pickup.schedules();
 ```
 
-This project was created using `bun init` in bun v1.3.3. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+---
+
+### Payment
+
+```ts
+await KiriminAja.payment.getPayment(orderId);
+```
+
+---
+
+## Nuxt / Nitro (h3 Adapter)
+
+The `kiriminaja/adapters/h3` sub-package wraps `init()` into a Nitro server plugin and provides a `useKiriminAja()` composable for event handlers — no extra dependencies required.
+
+### 1. Add your API key to runtime config
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+    runtimeConfig: {
+        kiriminajaApiKey: process.env.KIRIMINAJA_API_KEY,
+    },
+});
+```
+
+### 2. Create a server plugin
+
+```ts
+// server/plugins/kiriminaja.ts
+import { defineKiriminAjaPlugin, KAEnv } from "kiriminaja/adapters/h3";
+
+export default defineKiriminAjaPlugin(() => ({
+    apiKey: useRuntimeConfig().kiriminajaApiKey,
+    env: KAEnv.PRODUCTION,
+}));
+```
+
+> Pass a **factory function** (as above) when you need `useRuntimeConfig()` — it is called lazily when the plugin boots, not at import time. A plain options object also works if you read the key from `process.env` directly.
+
+### 3. Use in server routes
+
+```ts
+// server/api/rates.post.ts
+import { useKiriminAja } from "kiriminaja/adapters/h3";
+
+export default defineEventHandler(async (event) => {
+    const body = await readBody(event);
+    const { coverageArea } = useKiriminAja();
+    return coverageArea.pricingExpress(body);
+});
+```
+
+---
+
+## Per-user / Per-request API Keys
+
+If each user has their own KiriminAja API key, pass it directly to `useKiriminAja({ apiKey })`. No wrapper function needed — the key is scoped to that call and its entire async chain via `AsyncLocalStorage` internally, so concurrent requests are fully isolated.
+
+```ts
+// server/api/rates.post.ts
+import { useKiriminAja } from "kiriminaja/adapters/h3";
+
+export default defineEventHandler(async (event) => {
+    const user = await requireAuthUser(event);
+    const body = await readBody(event);
+
+    const { coverageArea } = useKiriminAja({ apiKey: user.kiriminajaApiKey });
+    return coverageArea.pricingExpress(body);
+});
+```
+
+Works on nested namespaces too:
+
+```ts
+const { order } = useKiriminAja({ apiKey: user.kiriminajaApiKey });
+await order.express.track("AWB123");
+```
+
+Calls made without `{ apiKey }` fall back to the key set in `defineKiriminAjaPlugin`.
+
+---
+
+## Development
+
+```bash
+bun install      # install dependencies
+bun test         # run tests
+bun run build    # compile to dist/
+```

package/dist/adapters/h3.d.ts

@@ -0,0 +1,120 @@
+import { type InitOptions } from "../config/client.js";
+import { KAEnv } from "../config/api.js";
+export { KAEnv };
+/**
+ * Creates a Nitro/h3 server plugin that initializes the KiriminAja SDK.
+ *
+ * Accepts either a plain options object or a factory function — use the
+ * factory form when you need to read Nuxt runtime config lazily (i.e. inside
+ * the plugin callback where `useRuntimeConfig()` is available).
+ *
+ * @example Plain options (shared API key)
+ * ```ts
+ * // server/plugins/kiriminaja.ts
+ * import { defineKiriminAjaPlugin, KAEnv } from 'kiriminaja/adapters/h3'
+ *
+ * export default defineKiriminAjaPlugin({
+ *   apiKey: process.env.KIRIMINAJA_API_KEY,
+ *   env: KAEnv.PRODUCTION,
+ * })
+ * ```
+ *
+ * @example With Nuxt runtime config
+ * ```ts
+ * // server/plugins/kiriminaja.ts
+ * import { defineKiriminAjaPlugin, KAEnv } from 'kiriminaja/adapters/h3'
+ * import { useRuntimeConfig } from '#imports'
+ *
+ * export default defineKiriminAjaPlugin(() => ({
+ *   apiKey: useRuntimeConfig().kiriminajaApiKey,
+ *   env: KAEnv.PRODUCTION,
+ * }))
+ * ```
+ */
+export declare const defineKiriminAjaPlugin: (options: InitOptions | (() => InitOptions)) => () => void;
+export type UseKiriminAjaOptions = {
+    apiKey?: string;
+};
+/**
+ * Returns the KiriminAja service methods for use inside Nitro/h3 event
+ * handlers or Nuxt server routes.
+ *
+ * - **No arguments** — uses the API key configured via `defineKiriminAjaPlugin`.
+ * - **`{ apiKey }`** — overrides the Authorization header for every service
+ *   call made on the returned object. Safe for concurrent requests; each call
+ *   runs in its own `AsyncLocalStorage` context so keys never bleed across
+ *   requests.
+ *
+ * The SDK **must** have been initialized (via `defineKiriminAjaPlugin`) before
+ * any service method is called.
+ *
+ * @example Shared API key (from plugin)
+ * ```ts
+ * // server/api/rates.post.ts
+ * import { useKiriminAja } from 'kiriminaja/adapters/h3'
+ *
+ * export default defineEventHandler(async (event) => {
+ *   const { coverageArea } = useKiriminAja()
+ *   const body = await readBody(event)
+ *   return coverageArea.pricingExpress(body)
+ * })
+ * ```
+ *
+ * @example Per-user API key
+ * ```ts
+ * // server/api/rates.post.ts
+ * import { useKiriminAja } from 'kiriminaja/adapters/h3'
+ *
+ * export default defineEventHandler(async (event) => {
+ *   const user = await requireAuthUser(event)
+ *   const body = await readBody(event)
+ *   const { coverageArea } = useKiriminAja({ apiKey: user.kiriminajaApiKey })
+ *   return coverageArea.pricingExpress(body)
+ * })
+ * ```
+ */
+export declare const useKiriminAja: (options?: UseKiriminAjaOptions) => {
+    address: {
+        provinces: () => Promise<import("../types/coverage-area.responses.js").ProvinceListResponse>;
+        cities: (provinsiId: number) => Promise<import("../types/coverage-area.responses.js").CityListResponse>;
+        districts: (kabupatenId: number) => Promise<import("../types/coverage-area.responses.js").DistrictListResponse>;
+        subDistricts: (kecamatanId: number) => Promise<import("../types/coverage-area.responses.js").SubDistrictListResponse>;
+        districtsByName: (search: string) => Promise<import("../types/coverage-area.responses.js").DistrictByNameResponse>;
+    };
+    coverageArea: {
+        pricingExpress: <T = unknown>(payload: import("../services/coverage-area/pricing-express.js").PricingExpressPayload) => Promise<import("../types/api-response.js").KAResponse<unknown>>;
+        pricingInstant: <T = unknown>(payload: import("../services/coverage-area/pricing-instant.js").PricingInstantPayload) => Promise<import("../types/api-response.js").KAResponse<unknown>>;
+        provinces: () => Promise<import("../types/coverage-area.responses.js").ProvinceListResponse>;
+        cities: (provinsiId: number) => Promise<import("../types/coverage-area.responses.js").CityListResponse>;
+        districts: (kabupatenId: number) => Promise<import("../types/coverage-area.responses.js").DistrictListResponse>;
+        subDistricts: (kecamatanId: number) => Promise<import("../types/coverage-area.responses.js").SubDistrictListResponse>;
+        districtsByName: (search: string) => Promise<import("../types/coverage-area.responses.js").DistrictByNameResponse>;
+    };
+    order: {
+        express: {
+            track: (orderId: string) => Promise<import("../types/order.responses.js").ExpressTrackingResponse>;
+            cancel: (awb: string, reason: string) => Promise<import("../types/order.responses.js").CancelExpressOrderResponse>;
+            requestPickupV5: (payload: unknown) => Promise<import("../types/api-response.js").KAResponse<unknown>>;
+            requestPickupV61: (payload: unknown) => Promise<import("../types/api-response.js").KAResponse<unknown>>;
+        };
+        instant: {
+            create: (payload: unknown) => Promise<unknown>;
+            findNewDriver: (orderId: string) => Promise<unknown>;
+            cancel: (orderId: string) => Promise<import("../types/order.responses.js").CancelInstantOrderResponse>;
+            track: (orderId: string) => Promise<import("../types/order.responses.js").InstantTrackingResponse>;
+        };
+    };
+    pickup: {
+        schedules: () => Promise<import("../types/pickup.responses.js").PickupSchedulesResponse>;
+    };
+    payment: {
+        getPayment: (paymentId: string) => Promise<import("../types/payment.responses.js").GetPaymentResponse>;
+    };
+    courier: {
+        list: () => Promise<import("../types/courier.js").CourierListResponse>;
+        group: () => Promise<import("../types/courier.js").CourierGroupResponse>;
+        detail: (courierCode: string) => Promise<import("../types/courier.js").CourierDetailResponse>;
+        setWhitelistServices: (services: string[]) => Promise<import("../types/courier.js").SetCourierPreferenceResponse>;
+    };
+};
+//# sourceMappingURL=h3.d.ts.map

package/dist/adapters/h3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"h3.d.ts","sourceRoot":"","sources":["../../src/adapters/h3.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAExE,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,sBAAsB,GAC/B,SAAS,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,eAM7C,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAM3D,CAAC"}

package/dist/adapters/h3.js

@@ -0,0 +1,86 @@
+import { init, getConfig } from "../config/client.js";
+import { services } from "../services/index.js";
+import { KAEnv } from "../config/api.js";
+export { KAEnv };
+/**
+ * Creates a Nitro/h3 server plugin that initializes the KiriminAja SDK.
+ *
+ * Accepts either a plain options object or a factory function — use the
+ * factory form when you need to read Nuxt runtime config lazily (i.e. inside
+ * the plugin callback where `useRuntimeConfig()` is available).
+ *
+ * @example Plain options (shared API key)
+ * ```ts
+ * // server/plugins/kiriminaja.ts
+ * import { defineKiriminAjaPlugin, KAEnv } from 'kiriminaja/adapters/h3'
+ *
+ * export default defineKiriminAjaPlugin({
+ *   apiKey: process.env.KIRIMINAJA_API_KEY,
+ *   env: KAEnv.PRODUCTION,
+ * })
+ * ```
+ *
+ * @example With Nuxt runtime config
+ * ```ts
+ * // server/plugins/kiriminaja.ts
+ * import { defineKiriminAjaPlugin, KAEnv } from 'kiriminaja/adapters/h3'
+ * import { useRuntimeConfig } from '#imports'
+ *
+ * export default defineKiriminAjaPlugin(() => ({
+ *   apiKey: useRuntimeConfig().kiriminajaApiKey,
+ *   env: KAEnv.PRODUCTION,
+ * }))
+ * ```
+ */
+export const defineKiriminAjaPlugin = (options) => {
+    return () => {
+        const resolved = typeof options === "function" ? options() : options;
+        init(resolved);
+    };
+};
+/**
+ * Returns the KiriminAja service methods for use inside Nitro/h3 event
+ * handlers or Nuxt server routes.
+ *
+ * - **No arguments** — uses the API key configured via `defineKiriminAjaPlugin`.
+ * - **`{ apiKey }`** — overrides the Authorization header for every service
+ *   call made on the returned object. Safe for concurrent requests; each call
+ *   runs in its own `AsyncLocalStorage` context so keys never bleed across
+ *   requests.
+ *
+ * The SDK **must** have been initialized (via `defineKiriminAjaPlugin`) before
+ * any service method is called.
+ *
+ * @example Shared API key (from plugin)
+ * ```ts
+ * // server/api/rates.post.ts
+ * import { useKiriminAja } from 'kiriminaja/adapters/h3'
+ *
+ * export default defineEventHandler(async (event) => {
+ *   const { coverageArea } = useKiriminAja()
+ *   const body = await readBody(event)
+ *   return coverageArea.pricingExpress(body)
+ * })
+ * ```
+ *
+ * @example Per-user API key
+ * ```ts
+ * // server/api/rates.post.ts
+ * import { useKiriminAja } from 'kiriminaja/adapters/h3'
+ *
+ * export default defineEventHandler(async (event) => {
+ *   const user = await requireAuthUser(event)
+ *   const body = await readBody(event)
+ *   const { coverageArea } = useKiriminAja({ apiKey: user.kiriminajaApiKey })
+ *   return coverageArea.pricingExpress(body)
+ * })
+ * ```
+ */
+export const useKiriminAja = (options) => {
+    if (options?.apiKey) {
+        const current = getConfig();
+        init({ ...current, apiKey: options.apiKey });
+    }
+    return services;
+};
+//# sourceMappingURL=h3.js.map

package/dist/adapters/h3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"h3.js","sourceRoot":"","sources":["../../src/adapters/h3.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,SAAS,EAAoB,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAClC,OAA0C,EAC5C,EAAE;IACA,OAAO,GAAG,EAAE;QACR,MAAM,QAAQ,GAAG,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QACrE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACnB,CAAC,CAAC;AACN,CAAC,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAA8B,EAAE,EAAE;IAC5D,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,MAAM,OAAO,GAAG,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,QAAQ,CAAC;AACpB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "kiriminaja",
-    "version": "0.1.4",
+    "version": "0.1.6",
     "module": "dist/index.js",
     "types": "dist/index.d.ts",
     "license": "MIT",
@@ -12,6 +12,10 @@
         ".": {
             "types": "./dist/index.d.ts",
             "import": "./dist/index.js"
+        },
+        "./adapters/h3": {
+            "types": "./dist/adapters/h3.d.ts",
+            "import": "./dist/adapters/h3.js"
         }
     },
     "files": [
@@ -21,6 +25,7 @@
     ],
     "devDependencies": {
         "@types/bun": "^1.3.11",
+        "@types/node": "^25.5.0",
         "changelogen": "^0.6.2",
         "typescript": "^6.0.0"
     },