@kirimdev/sdk 3.3.0 → 3.4.0
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/README.md +98 -98
- package/dist/generated/schema.d.ts +1 -0
- package/dist/generated/version.d.ts +1 -1
- package/dist/generated/version.js +1 -1
- package/dist/generated/version.ts +1 -1
- package/openapi.json +3 -0
- package/package.json +63 -63
package/README.md
CHANGED
|
@@ -1,98 +1,98 @@
|
|
|
1
|
-
# @kirimdev/sdk
|
|
2
|
-
|
|
3
|
-
Official TypeScript SDK for the [Kirimdev](https://kirimdev.com) Public API.
|
|
4
|
-
|
|
5
|
-
## Install
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
npm install @kirimdev/sdk
|
|
9
|
-
# or
|
|
10
|
-
bun add @kirimdev/sdk
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
## Quickstart
|
|
14
|
-
|
|
15
|
-
```ts
|
|
16
|
-
import { Kirim } from '@kirimdev/sdk'
|
|
17
|
-
|
|
18
|
-
const kirim = new Kirim({ apiKey: process.env.KIRIM_API_KEY! })
|
|
19
|
-
|
|
20
|
-
// Scope to a WhatsApp phone number (Meta `business_phone_number_id`).
|
|
21
|
-
// Look it up via `kirim.accounts.list()` if you don't have it handy.
|
|
22
|
-
const phone = kirim.phoneNumbers('106540352242922')
|
|
23
|
-
|
|
24
|
-
// Send a message
|
|
25
|
-
const msg = await phone.messages.send({
|
|
26
|
-
messaging_product: 'whatsapp',
|
|
27
|
-
to: '628123456789',
|
|
28
|
-
type: 'text',
|
|
29
|
-
text: { body: 'Halo dari SDK!' },
|
|
30
|
-
})
|
|
31
|
-
|
|
32
|
-
// Paginate
|
|
33
|
-
for await (const m of phone.messages.list({ limit: 50 })) {
|
|
34
|
-
console.log(m.id, m.status)
|
|
35
|
-
}
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
## Webhook verification
|
|
39
|
-
|
|
40
|
-
`verifyWebhookSignature` parses the `X-Kirim-Signature` header (Stripe-style
|
|
41
|
-
`t=<unix>,v1=<hex>` format), checks the timestamp against a tolerance window,
|
|
42
|
-
verifies the HMAC-SHA256 against one or more active secrets (supports rotation),
|
|
43
|
-
and returns the parsed JSON body. It **throws** on every failure mode — never
|
|
44
|
-
returns `false`. Uses Web Crypto so it runs unchanged on Node 18+, Bun, Deno,
|
|
45
|
-
and edge runtimes.
|
|
46
|
-
|
|
47
|
-
```ts
|
|
48
|
-
import { verifyWebhookSignature, InvalidSignatureError } from '@kirimdev/sdk/webhooks'
|
|
49
|
-
|
|
50
|
-
export async function POST(req: Request) {
|
|
51
|
-
const rawBody = await req.text()
|
|
52
|
-
try {
|
|
53
|
-
const event = await verifyWebhookSignature({
|
|
54
|
-
rawBody,
|
|
55
|
-
signatureHeader: req.headers.get('x-kirim-signature'),
|
|
56
|
-
secrets: [process.env.KIRIM_WEBHOOK_SECRET!],
|
|
57
|
-
})
|
|
58
|
-
// event is KirimWebhookEvent — narrow on event.type or event.object
|
|
59
|
-
return new Response('ok')
|
|
60
|
-
} catch (err) {
|
|
61
|
-
if (err instanceof InvalidSignatureError) return new Response('bad sig', { status: 401 })
|
|
62
|
-
throw err
|
|
63
|
-
}
|
|
64
|
-
}
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
Errors thrown (all extend `KirimWebhookError`):
|
|
68
|
-
|
|
69
|
-
- `InvalidSignatureError` — header missing/malformed, or no `v1=` matched any provided secret
|
|
70
|
-
- `SignatureExpiredError` — `|now - t|` exceeds `toleranceSeconds` (default 300s)
|
|
71
|
-
- `MalformedPayloadError` — signature matched but body is not valid JSON
|
|
72
|
-
|
|
73
|
-
## Features
|
|
74
|
-
|
|
75
|
-
- Full coverage of the Kirimdev `/v1` API (~35 endpoints)
|
|
76
|
-
- Type-safe — generated from the live OpenAPI 3.1 spec
|
|
77
|
-
- Automatic retries with exponential backoff (429, 5xx, network errors)
|
|
78
|
-
- Automatic `Idempotency-Key` injection for POST requests
|
|
79
|
-
- Async iterator pagination (`for await ... of kirim.messages.list(...)`)
|
|
80
|
-
- Typed error class hierarchy keyed off stable API error codes
|
|
81
|
-
- Webhook HMAC-SHA256 verifier
|
|
82
|
-
- Zero Node-specific dependencies — works in Node 18+, Bun, Deno
|
|
83
|
-
|
|
84
|
-
## Configuration
|
|
85
|
-
|
|
86
|
-
```ts
|
|
87
|
-
new Kirim({
|
|
88
|
-
apiKey: 'kdv_live_...', // required
|
|
89
|
-
baseUrl: 'https://api.kirimdev.com/v1', // optional
|
|
90
|
-
timeout: 30_000, // ms, default 30s
|
|
91
|
-
maxRetries: 2, // default 2
|
|
92
|
-
fetch: globalThis.fetch, // injectable for testing
|
|
93
|
-
})
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
## License
|
|
97
|
-
|
|
98
|
-
MIT
|
|
1
|
+
# @kirimdev/sdk
|
|
2
|
+
|
|
3
|
+
Official TypeScript SDK for the [Kirimdev](https://kirimdev.com) Public API.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @kirimdev/sdk
|
|
9
|
+
# or
|
|
10
|
+
bun add @kirimdev/sdk
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Quickstart
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { Kirim } from '@kirimdev/sdk'
|
|
17
|
+
|
|
18
|
+
const kirim = new Kirim({ apiKey: process.env.KIRIM_API_KEY! })
|
|
19
|
+
|
|
20
|
+
// Scope to a WhatsApp phone number (Meta `business_phone_number_id`).
|
|
21
|
+
// Look it up via `kirim.accounts.list()` if you don't have it handy.
|
|
22
|
+
const phone = kirim.phoneNumbers('106540352242922')
|
|
23
|
+
|
|
24
|
+
// Send a message
|
|
25
|
+
const msg = await phone.messages.send({
|
|
26
|
+
messaging_product: 'whatsapp',
|
|
27
|
+
to: '628123456789',
|
|
28
|
+
type: 'text',
|
|
29
|
+
text: { body: 'Halo dari SDK!' },
|
|
30
|
+
})
|
|
31
|
+
|
|
32
|
+
// Paginate
|
|
33
|
+
for await (const m of phone.messages.list({ limit: 50 })) {
|
|
34
|
+
console.log(m.id, m.status)
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Webhook verification
|
|
39
|
+
|
|
40
|
+
`verifyWebhookSignature` parses the `X-Kirim-Signature` header (Stripe-style
|
|
41
|
+
`t=<unix>,v1=<hex>` format), checks the timestamp against a tolerance window,
|
|
42
|
+
verifies the HMAC-SHA256 against one or more active secrets (supports rotation),
|
|
43
|
+
and returns the parsed JSON body. It **throws** on every failure mode — never
|
|
44
|
+
returns `false`. Uses Web Crypto so it runs unchanged on Node 18+, Bun, Deno,
|
|
45
|
+
and edge runtimes.
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import { verifyWebhookSignature, InvalidSignatureError } from '@kirimdev/sdk/webhooks'
|
|
49
|
+
|
|
50
|
+
export async function POST(req: Request) {
|
|
51
|
+
const rawBody = await req.text()
|
|
52
|
+
try {
|
|
53
|
+
const event = await verifyWebhookSignature({
|
|
54
|
+
rawBody,
|
|
55
|
+
signatureHeader: req.headers.get('x-kirim-signature'),
|
|
56
|
+
secrets: [process.env.KIRIM_WEBHOOK_SECRET!],
|
|
57
|
+
})
|
|
58
|
+
// event is KirimWebhookEvent — narrow on event.type or event.object
|
|
59
|
+
return new Response('ok')
|
|
60
|
+
} catch (err) {
|
|
61
|
+
if (err instanceof InvalidSignatureError) return new Response('bad sig', { status: 401 })
|
|
62
|
+
throw err
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Errors thrown (all extend `KirimWebhookError`):
|
|
68
|
+
|
|
69
|
+
- `InvalidSignatureError` — header missing/malformed, or no `v1=` matched any provided secret
|
|
70
|
+
- `SignatureExpiredError` — `|now - t|` exceeds `toleranceSeconds` (default 300s)
|
|
71
|
+
- `MalformedPayloadError` — signature matched but body is not valid JSON
|
|
72
|
+
|
|
73
|
+
## Features
|
|
74
|
+
|
|
75
|
+
- Full coverage of the Kirimdev `/v1` API (~35 endpoints)
|
|
76
|
+
- Type-safe — generated from the live OpenAPI 3.1 spec
|
|
77
|
+
- Automatic retries with exponential backoff (429, 5xx, network errors)
|
|
78
|
+
- Automatic `Idempotency-Key` injection for POST requests
|
|
79
|
+
- Async iterator pagination (`for await ... of kirim.messages.list(...)`)
|
|
80
|
+
- Typed error class hierarchy keyed off stable API error codes
|
|
81
|
+
- Webhook HMAC-SHA256 verifier
|
|
82
|
+
- Zero Node-specific dependencies — works in Node 18+, Bun, Deno
|
|
83
|
+
|
|
84
|
+
## Configuration
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
new Kirim({
|
|
88
|
+
apiKey: 'kdv_live_...', // required
|
|
89
|
+
baseUrl: 'https://api.kirimdev.com/v1', // optional
|
|
90
|
+
timeout: 30_000, // ms, default 30s
|
|
91
|
+
maxRetries: 2, // default 2
|
|
92
|
+
fetch: globalThis.fetch, // injectable for testing
|
|
93
|
+
})
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## License
|
|
97
|
+
|
|
98
|
+
MIT
|
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export declare const SDK_VERSION: "3.
|
|
1
|
+
export declare const SDK_VERSION: "3.4.0";
|
|
2
2
|
//# sourceMappingURL=version.d.ts.map
|
package/openapi.json
CHANGED
package/package.json
CHANGED
|
@@ -1,63 +1,63 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@kirimdev/sdk",
|
|
3
|
-
"version": "3.
|
|
4
|
-
"description": "Official TypeScript SDK for the Kirimdev Public API.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"license": "MIT",
|
|
7
|
-
"publishConfig": {
|
|
8
|
-
"access": "public",
|
|
9
|
-
"registry": "https://registry.npmjs.org/"
|
|
10
|
-
},
|
|
11
|
-
"keywords": [
|
|
12
|
-
"kirim",
|
|
13
|
-
"whatsapp",
|
|
14
|
-
"whatsapp-business",
|
|
15
|
-
"sdk",
|
|
16
|
-
"api-client"
|
|
17
|
-
],
|
|
18
|
-
"files": [
|
|
19
|
-
"dist",
|
|
20
|
-
"openapi.json",
|
|
21
|
-
"README.md",
|
|
22
|
-
"LICENSE"
|
|
23
|
-
],
|
|
24
|
-
"main": "./dist/index.js",
|
|
25
|
-
"module": "./dist/index.js",
|
|
26
|
-
"types": "./dist/index.d.ts",
|
|
27
|
-
"exports": {
|
|
28
|
-
".": {
|
|
29
|
-
"types": "./dist/index.d.ts",
|
|
30
|
-
"import": "./dist/index.js"
|
|
31
|
-
},
|
|
32
|
-
"./webhooks": {
|
|
33
|
-
"types": "./dist/webhooks.d.ts",
|
|
34
|
-
"import": "./dist/webhooks.js"
|
|
35
|
-
},
|
|
36
|
-
"./package.json": "./package.json"
|
|
37
|
-
},
|
|
38
|
-
"engines": {
|
|
39
|
-
"node": ">=18"
|
|
40
|
-
},
|
|
41
|
-
"scripts": {
|
|
42
|
-
"prebuild": "bun scripts/ensure-types.ts",
|
|
43
|
-
"build": "tsc -p tsconfig.build.json && bun scripts/copy-generated.ts",
|
|
44
|
-
"pretypecheck": "bun scripts/ensure-types.ts",
|
|
45
|
-
"typecheck": "tsc --noEmit",
|
|
46
|
-
"pretest": "bun scripts/ensure-types.ts",
|
|
47
|
-
"test": "bun test",
|
|
48
|
-
"lint": "tsc --noEmit",
|
|
49
|
-
"sync": "bun scripts/sync-openapi.ts && bun scripts/generate-types.ts",
|
|
50
|
-
"generate-types": "bun scripts/generate-types.ts",
|
|
51
|
-
"check:drift": "bun scripts/check-drift.ts",
|
|
52
|
-
"prepublishOnly": "bun run typecheck && bun run test && bun run build && bun scripts/verify-dist.ts"
|
|
53
|
-
},
|
|
54
|
-
"dependencies": {
|
|
55
|
-
"openapi-fetch": "^0.13.0"
|
|
56
|
-
},
|
|
57
|
-
"devDependencies": {
|
|
58
|
-
"@kirimdev/tsconfig": "workspace:*",
|
|
59
|
-
"@types/bun": "latest",
|
|
60
|
-
"openapi-typescript": "^7.4.0",
|
|
61
|
-
"typescript": "^5.8.0"
|
|
62
|
-
}
|
|
63
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@kirimdev/sdk",
|
|
3
|
+
"version": "3.4.0",
|
|
4
|
+
"description": "Official TypeScript SDK for the Kirimdev Public API.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"publishConfig": {
|
|
8
|
+
"access": "public",
|
|
9
|
+
"registry": "https://registry.npmjs.org/"
|
|
10
|
+
},
|
|
11
|
+
"keywords": [
|
|
12
|
+
"kirim",
|
|
13
|
+
"whatsapp",
|
|
14
|
+
"whatsapp-business",
|
|
15
|
+
"sdk",
|
|
16
|
+
"api-client"
|
|
17
|
+
],
|
|
18
|
+
"files": [
|
|
19
|
+
"dist",
|
|
20
|
+
"openapi.json",
|
|
21
|
+
"README.md",
|
|
22
|
+
"LICENSE"
|
|
23
|
+
],
|
|
24
|
+
"main": "./dist/index.js",
|
|
25
|
+
"module": "./dist/index.js",
|
|
26
|
+
"types": "./dist/index.d.ts",
|
|
27
|
+
"exports": {
|
|
28
|
+
".": {
|
|
29
|
+
"types": "./dist/index.d.ts",
|
|
30
|
+
"import": "./dist/index.js"
|
|
31
|
+
},
|
|
32
|
+
"./webhooks": {
|
|
33
|
+
"types": "./dist/webhooks.d.ts",
|
|
34
|
+
"import": "./dist/webhooks.js"
|
|
35
|
+
},
|
|
36
|
+
"./package.json": "./package.json"
|
|
37
|
+
},
|
|
38
|
+
"engines": {
|
|
39
|
+
"node": ">=18"
|
|
40
|
+
},
|
|
41
|
+
"scripts": {
|
|
42
|
+
"prebuild": "bun scripts/ensure-types.ts",
|
|
43
|
+
"build": "tsc -p tsconfig.build.json && bun scripts/copy-generated.ts",
|
|
44
|
+
"pretypecheck": "bun scripts/ensure-types.ts",
|
|
45
|
+
"typecheck": "tsc --noEmit",
|
|
46
|
+
"pretest": "bun scripts/ensure-types.ts",
|
|
47
|
+
"test": "bun test",
|
|
48
|
+
"lint": "tsc --noEmit",
|
|
49
|
+
"sync": "bun scripts/sync-openapi.ts && bun scripts/generate-types.ts",
|
|
50
|
+
"generate-types": "bun scripts/generate-types.ts",
|
|
51
|
+
"check:drift": "bun scripts/check-drift.ts",
|
|
52
|
+
"prepublishOnly": "bun run typecheck && bun run test && bun run build && bun scripts/verify-dist.ts"
|
|
53
|
+
},
|
|
54
|
+
"dependencies": {
|
|
55
|
+
"openapi-fetch": "^0.13.0"
|
|
56
|
+
},
|
|
57
|
+
"devDependencies": {
|
|
58
|
+
"@kirimdev/tsconfig": "workspace:*",
|
|
59
|
+
"@types/bun": "latest",
|
|
60
|
+
"openapi-typescript": "^7.4.0",
|
|
61
|
+
"typescript": "^5.8.0"
|
|
62
|
+
}
|
|
63
|
+
}
|