@kbve/droid 0.1.1 → 0.1.2

package/src/lib/agents/github/webhook.ts

@@ -0,0 +1,349 @@
+import type { AgentsCtx } from '../ctx';
+import type { AgentsApi } from '../api-types';
+import {
+	GithubRepoHookSchema,
+	WebhookDeliverySchema,
+} from '../generated/discordsh-agents-schema';
+import type {
+	GithubRepoHook,
+	Result,
+	WebhookDelivery,
+	WebhookInstallResult,
+} from '../types';
+
+export function makeWebhook(ctx: AgentsCtx, api: AgentsApi) {
+	const { store, endpoints } = ctx;
+
+	function setWebhookDraft(guildId: string, secret: string | null): void {
+		const m = { ...store.$webhookDrafts.get() };
+		if (secret === null) delete m[guildId];
+		else m[guildId] = secret;
+		store.$webhookDrafts.set(m);
+	}
+
+	function clearWebhookError(guildId: string): void {
+		const m = { ...store.$webhookErrors.get() };
+		delete m[guildId];
+		store.$webhookErrors.set(m);
+	}
+
+	async function saveWebhookDraft(
+		guildId: string,
+		tokenName: string,
+		description: string,
+	): Promise<Result<{ tokenId: string }>> {
+		const secret = store.$webhookDrafts.get()[guildId];
+		if (!secret) return { ok: false, error: 'No secret to save' };
+		store.$webhookSavingFor.set({
+			...store.$webhookSavingFor.get(),
+			[guildId]: true,
+		});
+		store.$webhookErrors.set({
+			...store.$webhookErrors.get(),
+			[guildId]: null,
+		});
+		const r = await api.addToken({
+			tokenName,
+			service: 'github_webhook',
+			tokenValue: secret,
+			description,
+		});
+		const savingDone = { ...store.$webhookSavingFor.get() };
+		delete savingDone[guildId];
+		store.$webhookSavingFor.set(savingDone);
+		if (r.ok) {
+			setWebhookDraft(guildId, null);
+		} else {
+			store.$webhookErrors.set({
+				...store.$webhookErrors.get(),
+				[guildId]: r.error,
+			});
+		}
+		return r;
+	}
+
+	async function installRepoWebhook(
+		guildId: string,
+		owner: string,
+		repo: string,
+	): Promise<WebhookInstallResult | { ok: false; error: string }> {
+		const r = await ctx.callJson<{
+			installed: boolean;
+			already_present: boolean;
+			hook_id: number | null;
+		}>(endpoints.ghAdmin, {
+			command: 'webhooks.install',
+			server_id: guildId,
+			owner,
+			repo,
+		});
+		if (!r.ok) return r;
+		return {
+			ok: true,
+			installed: !!r.data.installed,
+			alreadyPresent: !!r.data.already_present,
+			hookId: r.data.hook_id ?? null,
+		};
+	}
+
+	async function pingRepoWebhook(
+		guildId: string,
+		owner: string,
+		repo: string,
+	): Promise<
+		| { ok: true; hookId: number; url: string }
+		| { ok: false; error: string; retryAfterMs?: number }
+	> {
+		const r = await ctx.callJson<{
+			pinged: boolean;
+			hook_id: number;
+			url: string;
+		}>(endpoints.ghAdmin, {
+			command: 'webhooks.ping',
+			server_id: guildId,
+			owner,
+			repo,
+		});
+		if (!r.ok) return { ok: false, error: r.error };
+		return { ok: true, hookId: r.data.hook_id, url: r.data.url };
+	}
+
+	async function listRepoWebhooks(
+		guildId: string,
+		owner: string,
+		repo: string,
+	): Promise<Result<{ expectedUrl: string; hooks: GithubRepoHook[] }>> {
+		const r = await ctx.callJson<{
+			expected_url: string;
+			hooks: GithubRepoHook[];
+		}>(endpoints.ghAdmin, {
+			command: 'webhooks.list',
+			server_id: guildId,
+			owner,
+			repo,
+		});
+		if (!r.ok) return r;
+		const parsed = GithubRepoHookSchema.array().safeParse(
+			r.data.hooks ?? [],
+		);
+		if (!parsed.success) {
+			return {
+				ok: false,
+				error: 'Webhook list failed schema validation',
+			};
+		}
+		return {
+			ok: true,
+			expectedUrl: r.data.expected_url,
+			hooks: parsed.data,
+		};
+	}
+
+	function setWebhookInstallSelected(guildId: string, repo: string): void {
+		store.$webhookInstallSelected.set({
+			...store.$webhookInstallSelected.get(),
+			[guildId]: repo,
+		});
+	}
+
+	function clearWebhookInstallResult(guildId: string): void {
+		const m = { ...store.$webhookInstallResults.get() };
+		delete m[guildId];
+		store.$webhookInstallResults.set(m);
+	}
+
+	async function installWebhookForGuild(guildId: string): Promise<void> {
+		const repoFull = store.$webhookInstallSelected.get()[guildId] ?? '';
+		const [owner, repo] = repoFull.split('/');
+		if (!owner || !repo) return;
+		store.$webhookInstallBusyFor.set({
+			...store.$webhookInstallBusyFor.get(),
+			[guildId]: true,
+		});
+		const resultsClear = { ...store.$webhookInstallResults.get() };
+		delete resultsClear[guildId];
+		store.$webhookInstallResults.set(resultsClear);
+		const r = await installRepoWebhook(guildId, owner, repo);
+		const busyDone = { ...store.$webhookInstallBusyFor.get() };
+		delete busyDone[guildId];
+		store.$webhookInstallBusyFor.set(busyDone);
+		store.$webhookInstallResults.set({
+			...store.$webhookInstallResults.get(),
+			[guildId]: r,
+		});
+	}
+
+	async function pingWebhookForGuild(guildId: string): Promise<void> {
+		const repoFull = store.$webhookInstallSelected.get()[guildId] ?? '';
+		const [owner, repo] = repoFull.split('/');
+		if (!owner || !repo) return;
+		store.$webhookPingBusyFor.set({
+			...store.$webhookPingBusyFor.get(),
+			[guildId]: true,
+		});
+		const r = await pingRepoWebhook(guildId, owner, repo);
+		const busyDone = { ...store.$webhookPingBusyFor.get() };
+		delete busyDone[guildId];
+		store.$webhookPingBusyFor.set(busyDone);
+		const result = r.ok
+			? { ok: true as const, hookId: r.hookId, at: Date.now() }
+			: { ok: false as const, error: r.error };
+		store.$webhookPingResults.set({
+			...store.$webhookPingResults.get(),
+			[guildId]: result,
+		});
+	}
+
+	async function verifyWebhookInstall(
+		guildId: string,
+		repoFull: string,
+	): Promise<void> {
+		const [owner, repo] = repoFull.split('/');
+		if (!owner || !repo) return;
+		const cur = store.$webhookInstallResults.get()[guildId];
+		if (cur && cur.ok && (cur.installed || cur.alreadyPresent)) return;
+		const r = await listRepoWebhooks(guildId, owner, repo);
+		if (!r.ok) return;
+		const kbveHook = r.hooks.find((h) => h.is_kbve);
+		if (!kbveHook) return;
+		store.$webhookInstallResults.set({
+			...store.$webhookInstallResults.get(),
+			[guildId]: {
+				ok: true as const,
+				installed: false,
+				alreadyPresent: true,
+				hookId: kbveHook.id,
+			},
+		});
+	}
+
+	async function rotateWebhookForGuild(
+		guildId: string,
+		owner: string,
+		repo: string,
+	): Promise<void> {
+		store.$webhookRotateBusyFor.set({
+			...store.$webhookRotateBusyFor.get(),
+			[guildId]: true,
+		});
+		const r = await ctx.callJson<{ rotated: boolean; hook_id: number }>(
+			endpoints.ghAdmin,
+			{ command: 'webhooks.rotate', server_id: guildId, owner, repo },
+		);
+		const busy = { ...store.$webhookRotateBusyFor.get() };
+		delete busy[guildId];
+		store.$webhookRotateBusyFor.set(busy);
+		const result = r.ok
+			? { ok: true as const, hookId: r.data.hook_id, at: Date.now() }
+			: { ok: false as const, error: r.error };
+		store.$webhookRotateResults.set({
+			...store.$webhookRotateResults.get(),
+			[guildId]: result,
+		});
+		if (r.ok) {
+			await api.refreshSelectedGuild();
+		}
+	}
+
+	async function deleteWebhookForGuild(
+		guildId: string,
+		owner: string,
+		repo: string,
+	): Promise<Result> {
+		store.$webhookDeleteBusyFor.set({
+			...store.$webhookDeleteBusyFor.get(),
+			[guildId]: true,
+		});
+		const r = await ctx.callJson<{
+			deleted: boolean;
+			already_absent?: boolean;
+			hook_id?: number;
+		}>(endpoints.ghAdmin, {
+			command: 'webhooks.delete',
+			server_id: guildId,
+			owner,
+			repo,
+		});
+		const busy = { ...store.$webhookDeleteBusyFor.get() };
+		delete busy[guildId];
+		store.$webhookDeleteBusyFor.set(busy);
+		if (!r.ok) return { ok: false, error: r.error };
+		const results = { ...store.$webhookInstallResults.get() };
+		delete results[guildId];
+		store.$webhookInstallResults.set(results);
+		return { ok: true };
+	}
+
+	async function loadWebhookDeliveries(
+		guildId: string,
+		owner: string,
+		repo: string,
+		limit = 10,
+	): Promise<void> {
+		const key = `${guildId}:${owner}/${repo}`;
+		store.$webhookDeliveriesLoading.set({
+			...store.$webhookDeliveriesLoading.get(),
+			[key]: true,
+		});
+		store.$webhookDeliveriesError.set({
+			...store.$webhookDeliveriesError.get(),
+			[key]: null,
+		});
+		const r = await ctx.callJson<{
+			hook_id: number;
+			deliveries: WebhookDelivery[];
+		}>(endpoints.ghAdmin, {
+			command: 'webhooks.deliveries',
+			server_id: guildId,
+			owner,
+			repo,
+			limit,
+		});
+		const loading = { ...store.$webhookDeliveriesLoading.get() };
+		delete loading[key];
+		store.$webhookDeliveriesLoading.set(loading);
+		if (!r.ok) {
+			store.$webhookDeliveriesError.set({
+				...store.$webhookDeliveriesError.get(),
+				[key]: r.error,
+			});
+			return;
+		}
+		const parsed = WebhookDeliverySchema.array().safeParse(
+			r.data.deliveries ?? [],
+		);
+		if (!parsed.success) {
+			store.$webhookDeliveriesError.set({
+				...store.$webhookDeliveriesError.get(),
+				[key]: 'Delivery list failed schema validation',
+			});
+			return;
+		}
+		store.$webhookDeliveries.set({
+			...store.$webhookDeliveries.get(),
+			[key]: parsed.data,
+		});
+	}
+
+	function webhookUrlFor(guildId: string): string {
+		return `${endpoints.ghWebhookBase}/${guildId}`;
+	}
+
+	return {
+		setWebhookDraft,
+		clearWebhookError,
+		saveWebhookDraft,
+		installRepoWebhook,
+		pingRepoWebhook,
+		listRepoWebhooks,
+		setWebhookInstallSelected,
+		clearWebhookInstallResult,
+		installWebhookForGuild,
+		pingWebhookForGuild,
+		verifyWebhookInstall,
+		rotateWebhookForGuild,
+		deleteWebhookForGuild,
+		loadWebhookDeliveries,
+		webhookUrlFor,
+	};
+}

package/src/lib/agents/index.ts

@@ -0,0 +1,35 @@
+export { createAgents } from './createAgents';
+export type { AgentsApi, AgentsMethods } from './api-types';
+export type { AgentsStore } from './state/atoms';
+export type {
+	AgentsConfig,
+	AgentsNotice,
+	AgentsSession,
+	ResolvedAgentsConfig,
+} from './config';
+export {
+	emptyBotConfigFormDraft,
+	botConfigToFormDraft,
+	botConfigFromFormDraft,
+} from './formDrafts';
+export { parseJwtPayload, extractJwtOwnedGuildIds } from './cache';
+export type {
+	AgentTokenRow,
+	AuthState as AgentsAuthState,
+	BackfillResult,
+	BotConfigFormDraft,
+	DiscordChannel,
+	DiscordForumChannel,
+	DiscordGuild,
+	DiscordshConfig,
+	EventQueueStats,
+	FailedEvent,
+	GithubRepoHook,
+	GuildChannels,
+	PatValidation,
+	PendingEvent,
+	Result as AgentsResult,
+	WebhookDelivery,
+	WebhookInstallResult,
+	WebhookOpResult,
+} from './types';

package/src/lib/agents/state/atoms.ts

@@ -0,0 +1,122 @@
+import { atom, type WritableAtom } from 'nanostores';
+import { persistentAtom } from '@nanostores/persistent';
+import type {
+	AgentTokenRow,
+	AuthState,
+	BackfillResult,
+	BotConfigFormDraft,
+	DiscordGuild,
+	EventQueueStats,
+	FailedEvent,
+	GuildChannels,
+	PatValidation,
+	PendingEvent,
+	WebhookDelivery,
+	WebhookInstallResult,
+	WebhookOpResult,
+} from '../types';
+
+type Fail = { ok: false; error: string };
+
+function jsonPersistent<T>(key: string, fallback: T): WritableAtom<T> {
+	return persistentAtom<T>(key, fallback, {
+		encode: (v) => JSON.stringify(v),
+		decode: (raw) => {
+			try {
+				return raw ? (JSON.parse(raw) as T) : fallback;
+			} catch {
+				return fallback;
+			}
+		},
+	});
+}
+
+export function createAgentsStore() {
+	return {
+		$authState: atom<AuthState>('loading'),
+		$accessToken: atom<string | null>(null),
+		$providerToken: atom<string | null>(null),
+		$userId: atom<string | null>(null),
+
+		$guilds: atom<DiscordGuild[]>([]),
+		$guildsLoading: atom<boolean>(false),
+		$guildsError: atom<string | null>(null),
+		$guildsStale: atom<boolean>(false),
+
+		$selectedGuildId: atom<string | null>(null),
+
+		$tokens: atom<AgentTokenRow[]>([]),
+		$tokensLoading: atom<boolean>(false),
+		$tokensError: atom<string | null>(null),
+
+		$botConfigDrafts: atom<Record<string, BotConfigFormDraft>>({}),
+		$botConfigSavingFor: atom<Record<string, boolean>>({}),
+		$botConfigErrors: atom<Record<string, string | null>>({}),
+		$botConfigLoadedFor: atom<Record<string, boolean>>({}),
+
+		$repoAllowlistDrafts: atom<Record<string, string[]>>({}),
+		$repoAllowlistSavingFor: atom<Record<string, boolean>>({}),
+		$repoAllowlistErrors: atom<Record<string, string | null>>({}),
+		$repoAllowlistLoadedFor: atom<Record<string, boolean>>({}),
+
+		$webhookDrafts: atom<Record<string, string | null>>({}),
+		$webhookSavingFor: atom<Record<string, boolean>>({}),
+		$webhookErrors: atom<Record<string, string | null>>({}),
+
+		$patDrafts: atom<Record<string, string>>({}),
+		$patValidatedFor: atom<Record<string, PatValidation | null>>({}),
+		$patValidatingFor: atom<Record<string, boolean>>({}),
+		$patSavingFor: atom<Record<string, boolean>>({}),
+		$patErrors: atom<Record<string, string | null>>({}),
+
+		$backfillDrafts: atom<Record<string, { owner: string; repo: string }>>(
+			{},
+		),
+		$backfillBusyFor: atom<Record<string, boolean>>({}),
+		$backfillResults: atom<Record<string, BackfillResult | Fail | null>>(
+			{},
+		),
+
+		$webhookInstallSelected: atom<Record<string, string>>({}),
+		$webhookInstallBusyFor: atom<Record<string, boolean>>({}),
+		$webhookInstallResults: atom<
+			Record<string, WebhookInstallResult | Fail | null>
+		>({}),
+		$webhookPingBusyFor: atom<Record<string, boolean>>({}),
+		$webhookPingResults: atom<
+			Record<string, WebhookOpResult | Fail | null>
+		>({}),
+
+		$guildChannels: jsonPersistent<
+			Record<string, GuildChannels & { cached_at: number }>
+		>('kbve:agents:guild_channels:v1', {}),
+		$guildChannelsLoading: atom<Record<string, boolean>>({}),
+		$guildChannelsError: atom<Record<string, string | null>>({}),
+
+		$botMembership: jsonPersistent<
+			Record<string, { isMember: boolean; cached_at: number }>
+		>('kbve:agents:bot_membership:v1', {}),
+		$botMembershipLoading: atom<Record<string, boolean>>({}),
+		$botMembershipError: atom<Record<string, string | null>>({}),
+
+		$webhookDeliveries: atom<Record<string, WebhookDelivery[]>>({}),
+		$webhookDeliveriesLoading: atom<Record<string, boolean>>({}),
+		$webhookDeliveriesError: atom<Record<string, string | null>>({}),
+
+		$webhookRotateBusyFor: atom<Record<string, boolean>>({}),
+		$webhookRotateResults: atom<
+			Record<string, WebhookOpResult | Fail | null>
+		>({}),
+		$webhookDeleteBusyFor: atom<Record<string, boolean>>({}),
+
+		$eventStats: atom<Record<string, EventQueueStats>>({}),
+		$eventStatsLoading: atom<Record<string, boolean>>({}),
+		$failedEvents: atom<Record<string, FailedEvent[]>>({}),
+		$failedEventsLoading: atom<Record<string, boolean>>({}),
+		$pendingEvents: atom<Record<string, PendingEvent[]>>({}),
+		$pendingEventsLoading: atom<Record<string, boolean>>({}),
+		$eventRequeueBusyFor: atom<Record<string, boolean>>({}),
+	};
+}
+
+export type AgentsStore = ReturnType<typeof createAgentsStore>;

package/src/lib/agents/types.ts

@@ -0,0 +1,83 @@
+export type AuthState =
+	| 'loading'
+	| 'authenticated'
+	| 'unauthenticated'
+	| 'discord_reauth_required';
+
+export interface DiscordGuild {
+	id: string;
+	name: string;
+	icon: string | null;
+	owner: boolean;
+	permissions: string;
+}
+
+export interface BotConfigFormDraft {
+	default_repo: string;
+	claim_channel_id: string;
+	forum_channel_id: string;
+	noticeboard_channel_id: string;
+	taskboard_channel_id: string;
+	max_assignees: string;
+	mirror_pr_events: boolean;
+	active: boolean;
+}
+
+export type { AgentTokenRow, AgentError } from './generated/agents-schema';
+export type {
+	DiscordshConfig,
+	GithubRepoHook,
+	WebhookDelivery,
+	EventQueueStats,
+	FailedEvent,
+	PendingEvent,
+} from './generated/discordsh-agents-schema';
+
+export interface DiscordForumChannel {
+	id: string;
+	name: string;
+	parent_id: string | null;
+	position: number;
+}
+
+export interface DiscordChannel {
+	id: string;
+	name: string;
+	parent_id: string | null;
+	position: number;
+}
+
+export interface GuildChannels {
+	forums: DiscordChannel[];
+	texts: DiscordChannel[];
+}
+
+export interface PatValidation {
+	login: string;
+	scopes: string[];
+	tokenType: string;
+}
+
+export interface BackfillResult {
+	ok: true;
+	upserted: number;
+	pages: number;
+	rateLimitRemaining: number | null;
+}
+
+export interface WebhookInstallResult {
+	ok: true;
+	installed: boolean;
+	alreadyPresent: boolean;
+	hookId: number | null;
+}
+
+export interface WebhookOpResult {
+	ok: true;
+	hookId: number;
+	at: number;
+}
+
+export type Result<T = unknown> =
+	| ({ ok: true } & T)
+	| { ok: false; error: string };

package/src/lib/api.ts

@@ -0,0 +1,71 @@
+/**
+ * Unified API fetch for the KBVE web + mobile clients.
+ *
+ * One place for base-URL join, bearer auth, JSON headers, error parsing, and
+ * 204 handling — so callers stop reimplementing `authedFetch`/`publicGet` per
+ * component (which drifted and caused base-URL/CORS bugs). The `apiBase` is
+ * injected by the app (web dev = same-origin dev proxy, web prod = '', mobile
+ * = absolute origin) so this module stays platform-agnostic.
+ */
+
+export class ApiError extends Error {
+	status: number;
+	code?: string;
+	constructor(message: string, status: number, code?: string) {
+		super(message);
+		this.name = 'ApiError';
+		this.status = status;
+		this.code = code;
+	}
+}
+
+async function parseApiError(res: Response): Promise<ApiError> {
+	let detail = '';
+	let code: string | undefined;
+	try {
+		const txt = await res.text();
+		try {
+			const parsed = JSON.parse(txt) as {
+				message?: string;
+				error?: string;
+				detail?: string;
+			};
+			detail = parsed.message || parsed.error || parsed.detail || txt;
+			code = parsed.error;
+		} catch {
+			detail = txt;
+		}
+	} catch {
+		/* body already consumed or unavailable */
+	}
+	return new ApiError(detail || res.statusText, res.status, code);
+}
+
+export interface ApiFetchOptions extends RequestInit {
+	/** Bearer token; sets `Authorization` when present. */
+	token?: string | null;
+	/** Origin/prefix joined before `path`. '' = same-origin. */
+	apiBase?: string;
+}
+
+/**
+ * Fetch `${apiBase}${path}`, attaching the bearer token + JSON headers,
+ * throwing {@link ApiError} on non-2xx, and returning parsed JSON (or
+ * `undefined` for 204).
+ */
+export async function apiFetch<T>(
+	path: string,
+	opts: ApiFetchOptions = {},
+): Promise<T> {
+	const { token, apiBase = '', ...init } = opts;
+	const headers = new Headers(init.headers);
+	if (token) headers.set('Authorization', `Bearer ${token}`);
+	if (!headers.has('Accept')) headers.set('Accept', 'application/json');
+	if (init.body && !headers.has('Content-Type')) {
+		headers.set('Content-Type', 'application/json');
+	}
+	const res = await fetch(`${apiBase}${path}`, { ...init, headers });
+	if (!res.ok) throw await parseApiError(res);
+	if (res.status === 204) return undefined as T;
+	return (await res.json()) as T;
+}