feat: add webhook handling

- adds optional internal webhook server
- exposes function to handle events externally
- adds chat message events

Author: zSoulweaver

bun.lock

@@ -0,0 +1,34 @@
+import { env } from 'bun'
+import { Kient } from 'kient'
+
+const kient = new Kient()
+kient.setAuthToken(env.KICK_TOKEN as string)
+
+if (kient.webhookServerFetch) {
+	Bun.serve({
+		fetch: kient.webhookServerFetch,
+		port: 3000,
+	})
+}
+
+const subscription = await kient.api.webhook.subscribe({
+	method: 'webhook',
+	events: [
+		{
+			name: 'chat.message.sent',
+			version: 1,
+		},
+	],
+})
+console.log(subscription)
+
+const subscriptions = await kient.api.webhook.getSubscriptions()
+console.log(subscriptions.map((sub) => sub.raw))
+
+for (const sub of subscriptions) {
+	sub.unsubscribe()
+}
+
+kient.addListener('KIENT_CHAT_MESSAGE_SENT', (message) => {
+	console.log('chat message received from', message.sender.username)
+})

example/webhooks.ts

@@ -28,7 +28,6 @@
 		"@types/bun": "^1.1.6",
 		"bun-plugin-dts": "^0.3.0",
 		"changelogen": "^0.5.7",
-		"hono": "^4.7.2",
 		"typedoc": "^0.26.5",
 		"typedoc-plugin-markdown": "^4.2.3",
 		"typedoc-plugin-missing-exports": "^3.0.0",
@@ -40,6 +39,8 @@
 	},
 	"dependencies": {
 		"defu": "^6.1.4",
+		"destr": "^2.0.3",
+		"hono": "^4.7.2",
 		"nanoid": "^5.1.0",
 		"ofetch": "^1.3.4",
 		"pusher-js": "^8.4.0-rc2",

package.json

@@ -0,0 +1,16 @@
+import type { Kient } from 'kient'
+import type { APIResponse } from '../../util/api-response'
+import { SubscriptionEvent, type SubscriptionEventData } from '../../structures/subscription-event'
+
+export async function getEventSubscriptions(kient: Kient) {
+	const response =
+		await kient._apiClient.fetch<APIResponse<SubscriptionEventData[]>>('/events/subscriptions')
+
+	const subscriptionInstances = []
+	for (const subscription of response.data) {
+		const subscriptionEvent = new SubscriptionEvent(kient, subscription)
+		subscriptionInstances.push(subscriptionEvent)
+	}
+
+	return subscriptionInstances
+}

src/api/webhook/get-events.ts

@@ -0,0 +1,31 @@
+import { APIBase } from '../api-base'
+import { getEventSubscriptions } from './get-events'
+import { subscribeToEvent, type WebhookSubscriptionParams } from './subscribe'
+import { unsubscribeFromEvents } from './unsubscribe'
+/**
+ * Description placeholder
+ *
+ * @group APIs
+ */
+export class WebhookAPI extends APIBase {
+	/**
+	 * Returns an array of events that are currently subscribed to
+	 */
+	getSubscriptions() {
+		return getEventSubscriptions(this.kient)
+	}
+
+	/**
+	 * Subscribes to a specific event and returns details about subscription
+	 */
+	subscribe(params: WebhookSubscriptionParams) {
+		return subscribeToEvent(this.kient, params)
+	}
+
+	/**
+	 * Unsubscribes to an array of subscription IDs
+	 */
+	unsubscribe(ids: string[]) {
+		return unsubscribeFromEvents(this.kient, ids)
+	}
+}

src/api/webhook/index.ts

@@ -0,0 +1,35 @@
+import type { Kient } from 'kient'
+import type { APIResponse } from '../../util/api-response'
+import {
+	BasicSubscriptionEvent,
+	type BasicSubscriptionEventData,
+} from '../../structures/basic-subscription-event'
+
+export interface WebhookSubscriptionParams {
+	method: 'webhook'
+	events: Array<{
+		name: string
+		version: number
+	}>
+}
+
+export async function subscribeToEvent(kient: Kient, param: WebhookSubscriptionParams) {
+	const response = await kient._apiClient.fetch<APIResponse<BasicSubscriptionEventData[]>>(
+		'/events/subscriptions',
+		{
+			method: 'POST',
+			body: param,
+		},
+	)
+
+	const basicSubscriptionInstances = []
+	for (const subscription of response.data) {
+		if (subscription.error) {
+			throw new Error(subscription.error)
+		}
+		const basicSubscription = new BasicSubscriptionEvent(kient, subscription)
+		basicSubscriptionInstances.push(basicSubscription)
+	}
+
+	return basicSubscriptionInstances
+}

src/api/webhook/subscribe.ts

@@ -0,0 +1,12 @@
+import type { Kient } from 'kient'
+
+export async function unsubscribeFromEvents(kient: Kient, ids: string[]) {
+	const params = new URLSearchParams()
+	for (const id of ids) {
+		params.append('id', id.toString())
+	}
+
+	await kient._apiClient.fetch(`/events/subscriptions?${params}`, {
+		method: 'DELETE',
+	})
+}

src/api/webhook/unsubscribe.ts

@@ -1,3 +1,5 @@
+import { WebhookEvents } from './webhook.handler'
+
 const KientEvents = {
 	WebSocketConnected: 'KIENT_WEBSOCKET_CONNECTED',
 	WebSocketDisconnected: 'KIENT_WEBSOCKET_DISCONNECTED',
@@ -10,6 +12,7 @@ type CoreEvents = {
 
 export const Events = {
 	Core: KientEvents,
+	...WebhookEvents,
 }
 
-export type KientEventEmitters = CoreEvents
+export type KientEventEmitters = CoreEvents & WebhookEvents

src/events.ts

@@ -2,58 +2,73 @@ import defu from 'defu'
 import { EventEmitter } from 'tseep'
 import { APIClient, type APIClientOptions } from './api.client'
 import type { KientEventEmitters } from './events'
-import { WSClient, type WSClientOptions } from './ws.client'
 import { CategoryAPI } from './api/category'
 import { UserAPI } from './api/user'
 import { ChannelAPI } from './api/channel'
 import { ChatAPI } from './api/chat'
 import { MiscAPI } from './api/misc'
+import { WebhookAPI } from './api/webhook'
+import { WebhookServer } from './webhook.server'
+import { WebhookHandler } from './webhook.handler'
+import type { WebhookEvent } from './structures/base-event'
 
 type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T
 
 export interface KientOptions {
-	connectToWebsocket: boolean
 	apiClient: APIClientOptions
-	wsClient: WSClientOptions
+	webhookServer: {
+		enable: boolean
+	}
 }
 
 const defaultKientOptions: KientOptions = {
-	connectToWebsocket: true,
 	apiClient: {
 		ofetch: {
 			baseURL: 'https://api.kick.com/public/v1',
 		},
 	},
-	wsClient: {
-		pusher: {
-			appKey: '32cbd69e4b950bf97679',
-			cluster: 'us2',
-		},
+	webhookServer: {
+		enable: true,
 	},
 }
 
 export class Kient extends EventEmitter<KientEventEmitters> {
 	private readonly kientOptions: KientOptions
-	_wsClient?: WSClient
+	private _webhookServer?: WebhookServer
+	_webhookHandler: WebhookHandler
 	_apiClient: APIClient
+	_kickPublicKey?: string
 
 	constructor(options?: DeepPartial<KientOptions>) {
 		super()
 		this.kientOptions = defu(options as KientOptions, defaultKientOptions)
 
-		this.kientOptions.connectToWebsocket ? this.connectWebsocket() : null
+		if (this.kientOptions.webhookServer.enable) {
+			this.createWebhookServer()
+		}
 
 		this._apiClient = new APIClient(this, this.kientOptions.apiClient)
+		this._webhookHandler = new WebhookHandler(this)
 	}
 
-	connectWebsocket() {
-		this._wsClient = new WSClient(this, this.kientOptions.wsClient)
+	createWebhookServer() {
+		this._webhookServer = new WebhookServer(this)
 	}
 
-	setAuthToken(token: string) {
+	async setAuthToken(token: string) {
 		this._apiClient.setHeaders({
 			Authorization: `Bearer ${token}`,
 		})
+
+		this._kickPublicKey = await this.api.misc.getPublicKey()
+	}
+
+	get webhookServerFetch() {
+		return this._webhookServer?.fetch
+	}
+
+	handleWebhookEvent(event: WebhookEvent) {
+		this._webhookHandler.handleEvent(event)
 	}
 
 	api = {
@@ -62,5 +77,6 @@ export class Kient extends EventEmitter<KientEventEmitters> {
 		user: new UserAPI(this),
 		channel: new ChannelAPI(this),
 		chat: new ChatAPI(this),
+		webhook: new WebhookAPI(this),
 	}
 }

src/kient.ts

@@ -0,0 +1,37 @@
+import type { Kient } from '../kient'
+import { Base } from './base'
+
+export interface WebhookEvent {
+	messageId: string
+	timestamp: string
+	type: string
+	version: string
+	body: string
+}
+
+export class EventBase extends Base<WebhookEvent> {
+	/**
+	 * The information relating the received event
+	 */
+	webhookEvent: {
+		/**
+		 * The event's message id
+		 */
+		messageId: string
+
+		/**
+		 * The event's timestamp
+		 */
+		timestamp: Date
+	}
+
+	/** @internal */
+	constructor(kient: Kient, data: WebhookEvent) {
+		super(kient, data)
+
+		this.webhookEvent = {
+			messageId: data.messageId,
+			timestamp: new Date(data.timestamp),
+		}
+	}
+}