geekbot-cli 0.1.0

package/src/http/client.ts

@@ -0,0 +1,138 @@
+import { CliError } from "../errors/cli-error.ts";
+import { ExitCode } from "../errors/exit-codes.ts";
+import { API_BASE_URL, APP_VERSION } from "../utils/constants.ts";
+import { getBackoffMs, isRetryable, mapHttpError, parseErrorBody } from "./errors.ts";
+
+const MAX_RETRIES = 3;
+const INITIAL_BACKOFF_MS = 1000;
+
+export interface HttpClient {
+	get<T>(path: string, params?: Record<string, string>): Promise<T>;
+	post<T>(path: string, body: unknown): Promise<T>;
+	patch<T>(path: string, body: unknown): Promise<T>;
+	put<T>(path: string, body: unknown): Promise<T>;
+	delete(path: string): Promise<null>;
+}
+
+export function createHttpClient(
+	apiKey: string,
+	options?: { debug?: boolean },
+	fetchImpl?: typeof globalThis.fetch,
+): HttpClient {
+	const debug = options?.debug ?? false;
+	const _fetch = fetchImpl ?? globalThis.fetch;
+
+	async function request<T>(
+		method: string,
+		path: string,
+		body?: unknown,
+		params?: Record<string, string>,
+	): Promise<T> {
+		// Strip trailing slashes to avoid 301 redirects (API quirk)
+		const cleanPath = path.replace(/\/+$/, "");
+
+		let url = `${API_BASE_URL}${cleanPath}`;
+		if (params) {
+			const searchParams = new URLSearchParams();
+			for (const [key, value] of Object.entries(params)) {
+				if (value !== undefined && value !== "") {
+					searchParams.set(key, value);
+				}
+			}
+			const qs = searchParams.toString();
+			if (qs) {
+				url = `${url}?${qs}`;
+			}
+		}
+
+		for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+			try {
+				if (debug && attempt > 0) {
+					process.stderr.write(`[debug] Retry attempt ${attempt} for ${method} ${cleanPath}\n`);
+				}
+
+				const response = await _fetch(url, {
+					method,
+					headers: {
+						// Geekbot API expects raw token, NOT "Bearer <token>"
+						// WARNING: Authorization contains the raw API key.
+						// Never log request/response headers in debug mode.
+						Authorization: apiKey,
+						"Content-Type": "application/json",
+						"User-Agent": `geekbot-skill-cli/${APP_VERSION}`,
+					},
+					body: body !== undefined ? JSON.stringify(body) : undefined,
+				});
+
+				if (response.ok) {
+					// Handle 204 No Content (e.g., DELETE responses)
+					if (response.status === 204) {
+						return null as T;
+					}
+					// Runtime type validation is handled by Zod schema parsing at the call site
+					return (await response.json()) as T;
+				}
+
+				// Non-OK response -- parse error and decide retry vs throw
+				const errorMessage = await parseErrorBody(response);
+
+				if (debug) {
+					process.stderr.write(
+						`[debug] HTTP ${response.status} from ${method} ${cleanPath}: ${errorMessage}\n`,
+					);
+				}
+
+				if (isRetryable(response.status) && attempt < MAX_RETRIES) {
+					const backoff = getBackoffMs(response, attempt, INITIAL_BACKOFF_MS);
+					if (debug) {
+						process.stderr.write(`[debug] Retrying in ${backoff}ms\n`);
+					}
+					await Bun.sleep(backoff);
+					continue;
+				}
+
+				throw mapHttpError(response.status, errorMessage, cleanPath);
+			} catch (error) {
+				// Re-throw CliErrors (already mapped)
+				if (error instanceof CliError) throw error;
+
+				// Network-level errors (DNS failure, connection refused, timeout)
+				if (attempt < MAX_RETRIES) {
+					const backoff = INITIAL_BACKOFF_MS * 2 ** attempt;
+					if (debug) {
+						process.stderr.write(
+							`[debug] Network error (attempt ${attempt + 1}/${MAX_RETRIES + 1}): ${error instanceof Error ? error.message : String(error)}\n`,
+						);
+					}
+					await Bun.sleep(backoff);
+					continue;
+				}
+
+				throw new CliError(
+					`Network error: ${error instanceof Error ? error.message : String(error)}`,
+					"network_error",
+					ExitCode.NETWORK,
+					true,
+					"Check your internet connection and try again.",
+				);
+			}
+		}
+		// Unreachable: loop always returns or throws, but satisfies TS return check
+		throw new CliError(
+			"Request failed after all retries",
+			"network_error",
+			ExitCode.NETWORK,
+			true,
+			"Check your internet connection and try again.",
+		);
+	}
+
+	return {
+		get: <T>(path: string, params?: Record<string, string>) =>
+			request<T>("GET", path, undefined, params),
+		post: <T>(path: string, body: unknown) => request<T>("POST", path, body),
+		patch: <T>(path: string, body: unknown) => request<T>("PATCH", path, body),
+		put: <T>(path: string, body: unknown) => request<T>("PUT", path, body),
+		delete: (path: string) => request<null>("DELETE", path),
+	};
+}

package/src/http/errors.ts

@@ -0,0 +1,134 @@
+import { CliError } from "../errors/cli-error.ts";
+import { ExitCode } from "../errors/exit-codes.ts";
+
+/**
+ * Parse error body from API response.
+ * Handles two formats:
+ *   1. Object: { "error": "message" }
+ *   2. Bare JSON string: "Template not found"
+ */
+export async function parseErrorBody(response: Response): Promise<string> {
+	const text = await response.text();
+	try {
+		const json = JSON.parse(text);
+		if (typeof json === "object" && json !== null && typeof json.error === "string") {
+			return json.error;
+		}
+		if (typeof json === "string") {
+			return json;
+		}
+		return text;
+	} catch {
+		return text;
+	}
+}
+
+/**
+ * Map HTTP status code + error body to a CliError with correct exit code.
+ */
+export function mapHttpError(status: number, message: string, path: string): CliError {
+	switch (status) {
+		case 400:
+			return new CliError(
+				message || "Bad request",
+				"validation_error",
+				ExitCode.VALIDATION,
+				false,
+				"Check the request parameters and try again.",
+				{ path, status },
+			);
+		case 401:
+			return new CliError(
+				message || "Unauthorized",
+				"unauthorized",
+				ExitCode.AUTH,
+				false,
+				"Check your API key (GEEKBOT_API_KEY or --api-key). This error can also mean insufficient permissions for the resource.",
+				{ path, status },
+			);
+		case 403:
+			return new CliError(
+				message || "Forbidden",
+				"forbidden",
+				ExitCode.FORBIDDEN,
+				false,
+				"You don't have permission for this operation.",
+				{ path, status },
+			);
+		case 404:
+			return new CliError(
+				message || "Not found",
+				"not_found",
+				ExitCode.NOT_FOUND,
+				false,
+				undefined, // suggestion populated by buildNotFoundSuggestion when called from command handlers
+				{ path, status },
+			);
+		case 422:
+			return new CliError(
+				message || "Unprocessable entity",
+				"unprocessable",
+				ExitCode.VALIDATION,
+				false,
+				"The request was understood but could not be processed. Check field values.",
+				{ path, status },
+			);
+		case 429:
+			return new CliError(
+				message || "Rate limited",
+				"rate_limited",
+				ExitCode.API_ERROR,
+				true,
+				"Rate limited. Wait a moment and try again.",
+				{ path, status },
+			);
+		default:
+			if (status >= 500) {
+				return new CliError(
+					message || "Server error",
+					"server_error",
+					ExitCode.API_ERROR,
+					true,
+					"Geekbot API server error. Try again later.",
+					{ path, status },
+				);
+			}
+			return new CliError(
+				message || `HTTP ${status}`,
+				"api_error",
+				ExitCode.API_ERROR,
+				false,
+				undefined,
+				{ path, status },
+			);
+	}
+}
+
+/**
+ * Check if an HTTP status code is retryable.
+ * Only 429 (rate limit) and 5xx (server errors) are retried.
+ */
+export function isRetryable(status: number): boolean {
+	return status === 429 || status >= 500;
+}
+
+/** Maximum backoff delay in milliseconds (60 seconds). */
+export const MAX_BACKOFF_MS = 60_000;
+
+/**
+ * Calculate backoff delay for a retry attempt.
+ * Respects Retry-After header on 429 responses.
+ * All values are capped at MAX_BACKOFF_MS to prevent unbounded waits.
+ */
+export function getBackoffMs(response: Response, attempt: number, initialMs = 1000): number {
+	if (response.status === 429) {
+		const retryAfter = response.headers.get("Retry-After");
+		if (retryAfter) {
+			const seconds = Number.parseInt(retryAfter, 10);
+			if (!Number.isNaN(seconds) && seconds > 0) {
+				return Math.min(seconds * 1000, MAX_BACKOFF_MS);
+			}
+		}
+	}
+	return Math.min(initialMs * 2 ** attempt, MAX_BACKOFF_MS);
+}

package/src/output/envelope.ts

@@ -0,0 +1,50 @@
+import type { ErrorObject, FailureEnvelope, SuccessEnvelope } from "../types.ts";
+
+/**
+ * Create a success envelope for a single item.
+ * Shape: { ok: true, data: T, error: null, metadata: { timestamp, ...extra } }
+ */
+export function success<T>(data: T, meta?: Record<string, unknown>): SuccessEnvelope<T> {
+	return {
+		ok: true,
+		data,
+		error: null,
+		metadata: {
+			timestamp: new Date().toISOString(),
+			...meta,
+		},
+	};
+}
+
+/**
+ * Create a success envelope for a list of items.
+ * Shape: { ok: true, data: T[], error: null, metadata: { timestamp, count: N, ...extra } }
+ */
+export function successList<T>(data: T[], meta?: Record<string, unknown>): SuccessEnvelope<T[]> {
+	return {
+		ok: true,
+		data,
+		error: null,
+		metadata: {
+			timestamp: new Date().toISOString(),
+			count: data.length,
+			...meta,
+		},
+	};
+}
+
+/**
+ * Create a failure envelope from an ErrorObject.
+ * Shape: { ok: false, data: null, error: ErrorObject, metadata: { timestamp, ...extra } }
+ */
+export function failure(error: ErrorObject, meta?: Record<string, unknown>): FailureEnvelope {
+	return {
+		ok: false,
+		data: null,
+		error,
+		metadata: {
+			timestamp: new Date().toISOString(),
+			...meta,
+		},
+	};
+}

package/src/output/formatter.ts

@@ -0,0 +1,12 @@
+import type { OutputEnvelope } from "../types.ts";
+
+/**
+ * Write the output envelope to stdout as JSON.
+ * This is the ONLY function in the entire codebase that writes to stdout.
+ *
+ * Phase 1 always outputs JSON. Table output will be added in Phase 3 (CLI-07).
+ * The format parameter is accepted now for forward compatibility.
+ */
+export function writeOutput<T>(envelope: OutputEnvelope<T>, _format: "json" = "json"): void {
+	process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+}

package/src/schemas/common.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+/** Unix timestamp (seconds since epoch) as returned by the API */
+export const UnixTimestampSchema = z.number().int();
+
+/** Nullable string that defaults to null */
+export const NullableString = z.string().nullable();
+
+/** Days of week abbreviations used by the API */
+export const DayAbbreviation = z.enum(["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]);
+
+/** IANA timezone string */
+export const TimezoneSchema = z.string();

package/src/schemas/poll.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { FullUserSchema } from "./user.ts";
+
+/** Poll question within a poll */
+const PollQuestionSchema = z.object({
+	id: z.number(),
+	text: z.string(),
+	answer_type: z.string(),
+	answer_choices: z.array(z.string()),
+	add_own_options: z.boolean(),
+	one_option_limit: z.boolean(),
+});
+
+/** Poll recurrence settings */
+const PollRecurrenceSchema = z
+	.object({
+		type: z.string(),
+		repeat: z.number().nullable(),
+		every: z.string().nullable(),
+		day: z.string().nullable(),
+		month: z.string().nullable(),
+	})
+	.nullable();
+
+/** Poll schema matching actual Geekbot API response */
+export const PollSchema = z.object({
+	id: z.number(),
+	name: z.string(),
+	time: z.string(),
+	timezone: z.string(),
+	questions: z.array(PollQuestionSchema),
+	users: z.array(FullUserSchema),
+	recurrence: PollRecurrenceSchema,
+	sync_channel_members: z.boolean(),
+	sync_channel: z.string().nullable(),
+	dm_mode: z.boolean(),
+	anonymous: z.boolean(),
+	intro: z.string(),
+	creator: FullUserSchema,
+	users_total: z.number(),
+	paused: z.boolean(),
+});
+
+export type Poll = z.output<typeof PollSchema>;
+
+/** Poll list schema */
+export const PollListSchema = z.array(PollSchema);
+
+/** Poll vote answer within a result */
+const PollVoteAnswerSchema = z.object({
+	text: z.string(),
+	catergory_id: z.union([z.string(), z.number()]), // API typo preserved, can be "uncategorized" or number
+	votes: z.number(),
+	percentage: z.number(),
+	users: z.array(FullUserSchema).optional(),
+});
+
+/** Poll vote result for a specific date */
+const PollVoteResultSchema = z.object({
+	date: z.string().nullable(),
+	answers: z.array(PollVoteAnswerSchema),
+});
+
+/** Poll vote question with aggregated results */
+const PollVoteQuestionSchema = z.object({
+	id: z.number(),
+	text: z.string(),
+	answer_type: z.string(),
+	categories: z.array(z.union([z.string(), z.number()])),
+	total_responses: z.number(),
+	total_responders: z.number(),
+	results: z.array(PollVoteResultSchema),
+});
+
+/** Poll vote instance */
+const PollVoteInstanceSchema = z.object({
+	id: z.number(),
+	date: z.string().nullable(),
+	answer_count: z.number(),
+});
+
+/** Aggregated votes response from GET /v1/polls/{id}/votes */
+export const PollVotesResponseSchema = z.object({
+	total_results: z.number(),
+	questions: z.array(PollVoteQuestionSchema),
+	instances: z.array(PollVoteInstanceSchema),
+});
+
+export type PollVotesResponse = z.output<typeof PollVotesResponseSchema>;

package/src/schemas/report.ts

@@ -0,0 +1,124 @@
+import { z } from "zod";
+import { CompactUserSchema } from "./user.ts";
+
+/** Answer within a report (shared fields between GET and POST responses) */
+const ReportAnswerSchema = z.object({
+	id: z.number(),
+	question: z.string().optional().default(""),
+	question_id: z.number().optional(),
+	answer: z.string(),
+	answer_type: z.string().optional().default("text"),
+	images: z
+		.array(
+			z.object({
+				title: z.string(),
+				image_url: z.string(),
+			}),
+		)
+		.optional()
+		.default([]),
+	color: z.string().optional().default(""),
+});
+
+export type ReportAnswer = z.output<typeof ReportAnswerSchema>;
+
+/**
+ * Timeline report format (GET /v1/reports).
+ * API returns: id, slack_ts, standup_id, timestamp, channel, is_anonymous,
+ * broadcast_thread, is_confidential, member (CompactUser), questions (answers array)
+ */
+const TimelineReportRawSchema = z.object({
+	id: z.number(),
+	standup_id: z.number(),
+	timestamp: z.number(),
+	slack_ts: z.string().nullable().optional(),
+	channel: z.string().optional().default(""),
+	questions: z.array(ReportAnswerSchema),
+	member: CompactUserSchema,
+	is_anonymous: z.boolean().optional().default(false),
+	broadcast_thread: z.boolean().optional().default(false),
+	is_confidential: z.boolean().optional().default(false),
+	standup_name: z.string().optional().default(""),
+});
+
+/**
+ * Submitted report format (POST /v1/reports).
+ * API returns: id, slack_ts, standup_id, timestamp, started_at, done_at,
+ * broadcasted_at, channel, member (CompactUser with role), answers (array)
+ */
+const SubmittedReportRawSchema = z.object({
+	id: z.number(),
+	standup_id: z.number(),
+	timestamp: z.number(),
+	slack_ts: z.string().nullable().optional(),
+	started_at: z.number().optional(),
+	done_at: z.number().optional(),
+	broadcasted_at: z.number().nullable().optional(),
+	channel: z.string().optional().default(""),
+	member: z
+		.object({
+			id: z.string(),
+			role: z.string().optional(),
+			username: z.string(),
+			realname: z.string().nullable(),
+			profileImg: z.string(),
+		})
+		.optional(),
+	answers: z.array(ReportAnswerSchema),
+	is_anonymous: z.boolean().optional().default(false),
+});
+
+/**
+ * Unified Report type. Both formats normalize to this shape.
+ * NORM-03: Two different API response formats -> one consistent type.
+ */
+export interface Report {
+	id: number;
+	standup_id: number;
+	created_at: string;
+	questions: ReportAnswer[];
+	member: { id: string; username: string; realname: string | null; profile_img: string } | null;
+	is_anonymous: boolean;
+	standup_name: string;
+}
+
+/** Normalize a raw timeline report to the unified Report shape */
+function normalizeTimelineReport(raw: z.output<typeof TimelineReportRawSchema>): Report {
+	return {
+		id: raw.id,
+		standup_id: raw.standup_id,
+		created_at: new Date(raw.timestamp * 1000).toISOString(),
+		questions: raw.questions,
+		member: raw.member, // Already normalized by CompactUserSchema (profileImg -> profile_img)
+		is_anonymous: raw.is_anonymous,
+		standup_name: raw.standup_name,
+	};
+}
+
+/** Parse a timeline report (GET) and normalize to unified Report */
+export const TimelineReportSchema = TimelineReportRawSchema.transform(normalizeTimelineReport);
+
+/** Parse a submitted report (POST) and normalize to unified Report */
+export const SubmittedReportSchema = SubmittedReportRawSchema.transform(
+	(raw): Report => ({
+		id: raw.id,
+		standup_id: raw.standup_id,
+		created_at: new Date(raw.timestamp * 1000).toISOString(),
+		questions: raw.answers, // POST uses "answers" key, normalize to "questions"
+		member: raw.member
+			? {
+					id: raw.member.id,
+					username: raw.member.username,
+					realname: raw.member.realname,
+					profile_img: raw.member.profileImg,
+				}
+			: null,
+		is_anonymous: raw.is_anonymous,
+		standup_name: "",
+	}),
+);
+
+/** Parse a list of timeline reports */
+export const TimelineReportListSchema = z
+	.array(TimelineReportRawSchema)
+	.transform((items) => items.map(normalizeTimelineReport));

package/src/schemas/standup.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { DayAbbreviation, NullableString, TimezoneSchema } from "./common.ts";
+import { FullUserSchema } from "./user.ts";
+
+export const QuestionSchema = z.object({
+	id: z.number(),
+	color: z.string(),
+	text: z.string(),
+	schedule: z.unknown().nullable(),
+	answer_type: z.string(),
+	answer_choices: z.array(z.string()),
+	hasAnswers: z.boolean(),
+	is_random: z.boolean(),
+	random_texts: z.array(z.string()),
+	prefilled_by: z.unknown().nullable(),
+	text_id: z.number().nullable(),
+	preconditions: z.array(z.unknown()),
+	label: NullableString,
+	flavor: z.string(),
+});
+
+export type Question = z.output<typeof QuestionSchema>;
+
+/** Raw standup schema as returned by the API (wait_time in seconds) */
+const StandupRawSchema = z.object({
+	id: z.number(),
+	name: z.string(),
+	channel: z.string(),
+	channel_id: z.string().optional(),
+	time: z.string(),
+	timezone: TimezoneSchema,
+	days: z.array(DayAbbreviation),
+	questions: z.array(QuestionSchema),
+	users: z.array(FullUserSchema),
+	wait_time: z.number(), // API returns seconds
+	personalised: z.boolean().optional(),
+	confidential: z.boolean(),
+	anonymous: z.boolean(),
+	sync_channel_members: z.boolean().optional(),
+	master_id: z.number().nullable().optional(),
+	channel_ready: z.boolean().optional(),
+	draft: z.boolean().optional(),
+	paused: z.boolean().optional(),
+	users_total: z.number().optional(),
+	webhooks: z.array(z.unknown()).optional(),
+	master: z.unknown().nullable().optional(),
+	sync_channel_ready: z.boolean().optional(),
+	sync_channel: z.string().nullable().optional(),
+});
+
+/** Normalize a raw standup: convert wait_time from seconds to minutes */
+function normalizeStandup(raw: z.output<typeof StandupRawSchema>) {
+	return { ...raw, wait_time: raw.wait_time / 60 }; // NORM: seconds -> minutes (Pitfall 1)
+}
+
+/** Normalized standup -- wait_time converted from seconds to minutes */
+export const StandupSchema = StandupRawSchema.transform(normalizeStandup);
+
+export type Standup = z.output<typeof StandupSchema>;
+
+/** Schema for an array of standups */
+export const StandupListSchema = z
+	.array(StandupRawSchema)
+	.transform((items) => items.map(normalizeStandup));

package/src/schemas/team.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { FullUserSchema } from "./user.ts";
+
+/** GET /v1/teams returns a single team object (not array) */
+export const TeamResponseSchema = z.object({
+	id: z.number(),
+	name: z.string(),
+	users: z.array(FullUserSchema),
+});
+
+export type TeamResponse = z.output<typeof TeamResponseSchema>;