@tightknitai/tightknit 0.1.0-alpha.0

package/src/cli/index.ts

@@ -0,0 +1,99 @@
+import { Command } from "commander";
+
+// Events
+import { listEventsCommand } from "./events/list";
+import { getEventCommand } from "./events/get";
+import { createEventCommand } from "./events/create";
+import { updateAttendeeCommand } from "./events/update";
+import { deleteEventCommand } from "./events/delete";
+
+// Awards
+import { assignAwardCommand } from "./awards/assign";
+
+// Feeds
+import { listFeedsCommand } from "./feeds/list";
+import { getFeedCommand } from "./feeds/get";
+import { listPostsInFeedCommand } from "./feeds/posts";
+
+// Posts
+import { getPostCommand } from "./posts/get";
+
+// Members
+import { addMemberCommand } from "./members/add";
+import { checkMemberCommand } from "./members/check";
+
+// Messages
+import { sendMessageCommand } from "./messages/send";
+
+// Groups
+import { addGroupMemberCommand } from "./groups/add-member";
+
+// Search
+import { searchCommand } from "./search/query";
+
+// Config
+import { setConfigCommand } from "./config/set";
+import { getConfigCommand } from "./config/get";
+
+/** Create and configure the root CLI program */
+export function createProgram(): Command {
+  const program = new Command("tightknit")
+    .description("Tightknit CLI — manage your community from the command line")
+    .option("--no-color", "Disable colored output")
+    .option("--verbose", "Enable verbose output");
+
+  // Events command group
+  const events = new Command("events").description("Manage calendar events");
+  events.addCommand(listEventsCommand);
+  events.addCommand(getEventCommand);
+  events.addCommand(createEventCommand);
+  events.addCommand(updateAttendeeCommand);
+  events.addCommand(deleteEventCommand);
+  program.addCommand(events);
+
+  // Awards command group
+  const awards = new Command("awards").description("Manage awards");
+  awards.addCommand(assignAwardCommand);
+  program.addCommand(awards);
+
+  // Feeds command group
+  const feeds = new Command("feeds").description("Manage feeds");
+  feeds.addCommand(listFeedsCommand);
+  feeds.addCommand(getFeedCommand);
+  feeds.addCommand(listPostsInFeedCommand);
+  program.addCommand(feeds);
+
+  // Posts command group
+  const posts = new Command("posts").description("Manage posts");
+  posts.addCommand(getPostCommand);
+  program.addCommand(posts);
+
+  // Members command group
+  const members = new Command("members").description("Manage community members");
+  members.addCommand(addMemberCommand);
+  members.addCommand(checkMemberCommand);
+  program.addCommand(members);
+
+  // Messages command group
+  const messages = new Command("messages").description("Send Slack messages");
+  messages.addCommand(sendMessageCommand);
+  program.addCommand(messages);
+
+  // Groups command group
+  const groups = new Command("groups").description("Manage groups");
+  groups.addCommand(addGroupMemberCommand);
+  program.addCommand(groups);
+
+  // Search command group
+  const searchGroup = new Command("search").description("[Beta] Search documents");
+  searchGroup.addCommand(searchCommand);
+  program.addCommand(searchGroup);
+
+  // Config command group
+  const config = new Command("config").description("Manage CLI configuration");
+  config.addCommand(setConfigCommand);
+  config.addCommand(getConfigCommand);
+  program.addCommand(config);
+
+  return program;
+}

package/src/cli/members/add.ts

@@ -0,0 +1,28 @@
+import { Command } from "commander";
+import { addMember } from "../../core/client";
+import { printOutput, printSuccess } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const addMemberCommand = new Command("add")
+  .description("Add a member to the community (Enterprise)")
+  .requiredOption("--email <email>", "Member email address")
+  .requiredOption("--full-name <name>", "Member full name (first and last)")
+  .option("--avatar-url <url>", "Avatar image URL")
+  .option("--json", "Output as JSON")
+  .action(async (opts) => {
+    try {
+      const result = await addMember({
+        email: opts.email,
+        full_name: opts.fullName,
+        avatar_url_original: opts.avatarUrl,
+      });
+      if (opts.json) {
+        printOutput(result, { json: true });
+      } else {
+        printSuccess("Member added successfully");
+        printOutput(result, {});
+      }
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/members/check.ts

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+import { checkMembership } from "../../core/client";
+import { printOutput } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const checkMemberCommand = new Command("check")
+  .description("Check if an email is a community member")
+  .argument("<email>", "Email address to check")
+  .option("--json", "Output as JSON")
+  .action(async (email: string, opts) => {
+    try {
+      const result = await checkMembership(email);
+      printOutput(result, { json: opts.json });
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/messages/send.ts

@@ -0,0 +1,27 @@
+import { Command } from "commander";
+import { sendMessage } from "../../core/client";
+import { printOutput, printSuccess } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const sendMessageCommand = new Command("send")
+  .description("Send a Slack message to a channel or user")
+  .requiredOption("--channel <id>", "Slack channel ID (e.g. C0123456) or user ID")
+  .requiredOption("--text <text>", "Message text (plain text or Slack mrkdwn)")
+  .option("--thread-ts <ts>", "Reply to a thread (message timestamp)")
+  .option("--json", "Output as JSON")
+  .action(async (opts) => {
+    try {
+      const result = await sendMessage({
+        channel: opts.channel,
+        text: opts.text,
+        thread_ts: opts.threadTs,
+      });
+      if (opts.json) {
+        printOutput(result, { json: true });
+      } else {
+        printSuccess("Message sent");
+      }
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/posts/get.ts

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+import { getPost } from "../../core/client";
+import { printOutput } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const getPostCommand = new Command("get")
+  .description("Retrieve a post by ID")
+  .argument("<post-id>", "Post ID")
+  .option("--json", "Output as JSON")
+  .action(async (postId: string, opts) => {
+    try {
+      const result = await getPost(postId);
+      printOutput(result, { json: opts.json });
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/cli/search/query.ts

@@ -0,0 +1,25 @@
+import { Command } from "commander";
+import { search } from "../../core/client";
+import { printOutput } from "../../core/output";
+import { handleCommandError } from "../error-handler";
+
+export const searchCommand = new Command("query")
+  .description("[Beta] Search documents")
+  .argument("<query>", "Search query string")
+  .requiredOption("--type <type>", "Entity type: post, comment, content_resource")
+  .option("--page <number>", "Page number (0-indexed)", "0")
+  .option("--per-page <number>", "Records per page", "25")
+  .option("--json", "Output as JSON")
+  .action(async (query: string, opts) => {
+    try {
+      const result = await search({
+        q: query,
+        type: opts.type,
+        page: Number(opts.page),
+        per_page: Number(opts.perPage),
+      });
+      printOutput(result.data, { json: opts.json });
+    } catch (error) {
+      handleCommandError(error, opts.json);
+    }
+  });

package/src/core/client.ts

@@ -0,0 +1,297 @@
+import { getApiKey } from "./config";
+import type { ApiError } from "./types";
+
+const BASE_URL = "https://api.tightknit.ai";
+const API_PREFIX = "/admin/v0";
+
+interface RequestOptions {
+  method?: "GET" | "POST" | "PATCH" | "DELETE";
+  body?: Record<string, unknown>;
+  params?: Record<string, string | number | boolean | undefined>;
+  idempotencyKey?: string;
+}
+
+/** Build a URL with query parameters */
+function buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+  const url = new URL(`${API_PREFIX}${path}`, BASE_URL);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  return url.toString();
+}
+
+/** Parse an API error response into a structured error */
+async function parseErrorResponse(response: Response): Promise<ApiError> {
+  let message: string;
+  try {
+    const body = await response.json() as Record<string, unknown>;
+    message = (body.message as string) || (body.error as string) || response.statusText;
+  } catch {
+    message = response.statusText;
+  }
+
+  return {
+    error: true,
+    code: response.status,
+    message: `${message} (${response.status})`,
+  };
+}
+
+/** Make an authenticated request to the Tightknit API */
+export async function apiRequest<T>(path: string, options: RequestOptions = {}): Promise<T> {
+  const { method = "GET", body, params, idempotencyKey } = options;
+
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    throw new TightknitApiError(
+      'No API key configured. Run: tightknit config set api-key <YOUR_KEY>',
+      401
+    );
+  }
+
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${apiKey}`,
+    "Content-Type": "application/json",
+  };
+
+  if (idempotencyKey && (method === "POST" || method === "PATCH")) {
+    headers["Idempotency-Key"] = idempotencyKey;
+  }
+
+  const url = buildUrl(path, params);
+
+  const response = await fetch(url, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const apiError = await parseErrorResponse(response);
+    throw new TightknitApiError(apiError.message, apiError.code);
+  }
+
+  if (response.status === 204) {
+    return undefined as T;
+  }
+
+  return (await response.json()) as T;
+}
+
+/** Custom error class for Tightknit API errors */
+export class TightknitApiError extends Error {
+  code: number;
+
+  constructor(message: string, code: number) {
+    super(message);
+    this.name = "TightknitApiError";
+    this.code = code;
+  }
+
+  toJSON(): ApiError {
+    return {
+      error: true,
+      code: this.code,
+      message: this.message,
+    };
+  }
+}
+
+// --- Calendar Events ---
+// Paths use underscores: /calendar_events
+
+export interface ListEventsParams {
+  page?: number;
+  per_page?: number;
+  time_filter?: "upcoming" | "past";
+  date_filter?: string;
+  status?: "draft" | "needs_approval" | "published";
+  published_to_site?: boolean;
+  is_unlisted?: boolean;
+  feed_id?: string;
+  tag_ids?: string;
+}
+
+export async function listEvents(params?: ListEventsParams) {
+  return apiRequest<{ data: unknown[]; page: number; per_page: number }>(
+    "/calendar_events",
+    { params: params as Record<string, string | number | boolean | undefined> }
+  );
+}
+
+export interface CreateEventInput {
+  title: string;
+  description: string;
+  start_date: string;
+  end_date: string;
+  location?: string;
+  link?: string;
+  status?: "needs_approval" | "published";
+  slug?: string;
+  publish_to_site?: boolean;
+  is_unlisted?: boolean;
+  allow_public_guest_list?: boolean;
+  enable_registration_button?: boolean;
+  triggers_webhooks?: boolean;
+  external_speakers?: string;
+  cover_image_file_id?: string;
+  reminders_config?: number[];
+  publish_to_slack_channels?: string[];
+}
+
+export async function createEvent(input: CreateEventInput) {
+  return apiRequest<{ success: boolean; data: { calendar_event_id: string } }>("/calendar_events", {
+    method: "POST",
+    body: input as unknown as Record<string, unknown>,
+    idempotencyKey: crypto.randomUUID(),
+  });
+}
+
+export async function getEvent(id: string) {
+  return apiRequest<unknown>(`/calendar_events/${id}`);
+}
+
+export async function deleteEvent(id: string) {
+  return apiRequest<void>(`/calendar_events/${id}`, { method: "DELETE" });
+}
+
+export interface UpdateAttendeeInput {
+  user: { slack_user_id: string } | { email: string } | { profile_id: string };
+  personal_join_link?: string;
+}
+
+export async function updateAttendee(eventId: string, input: UpdateAttendeeInput) {
+  return apiRequest<unknown>(`/calendar_events/${eventId}/attendees`, {
+    method: "PATCH",
+    body: input as unknown as Record<string, unknown>,
+    idempotencyKey: crypto.randomUUID(),
+  });
+}
+
+// --- Awards ---
+
+export interface AssignAwardInput {
+  recipient: { slack_user_id: string } | { email: string } | { profile_id: string };
+  sender?: { slack_user_id: string } | { email: string } | { profile_id: string } | null;
+  send_anonymously?: boolean;
+}
+
+export async function assignAward(awardId: string, input: AssignAwardInput) {
+  return apiRequest<{ success: boolean }>(`/awards/${awardId}/assign`, {
+    method: "POST",
+    body: input as unknown as Record<string, unknown>,
+    idempotencyKey: crypto.randomUUID(),
+  });
+}
+
+// --- Feeds ---
+
+export interface ListFeedsParams {
+  page?: number;
+  per_page?: number;
+  is_unlisted?: boolean;
+  is_archived?: boolean;
+}
+
+export async function listFeeds(params?: ListFeedsParams) {
+  return apiRequest<{ data: unknown[]; page: number; per_page: number }>(
+    "/feeds",
+    { params: params as Record<string, string | number | boolean | undefined> }
+  );
+}
+
+export async function getFeed(feedId: string) {
+  return apiRequest<unknown>(`/feeds/${feedId}`);
+}
+
+export interface ListPostsInFeedParams {
+  page?: number;
+  per_page?: number;
+  sort?: "oldest" | "newest" | "most-recent-activity";
+}
+
+export async function listPostsInFeed(feedId: string, params?: ListPostsInFeedParams) {
+  return apiRequest<{ data: unknown[]; page: number; per_page: number }>(
+    `/feeds/${feedId}/posts`,
+    { params: params as Record<string, string | number | boolean | undefined> }
+  );
+}
+
+// --- Posts ---
+
+export async function getPost(postId: string) {
+  return apiRequest<unknown>(`/posts/${postId}`);
+}
+
+// --- Members ---
+
+export interface AddMemberInput {
+  email: string;
+  full_name: string;
+  avatar_url_original?: string;
+}
+
+export async function addMember(input: AddMemberInput) {
+  return apiRequest<unknown>("/members", {
+    method: "POST",
+    body: input as unknown as Record<string, unknown>,
+    idempotencyKey: crypto.randomUUID(),
+  });
+}
+
+export async function checkMembership(email: string) {
+  return apiRequest<unknown>("/members/check", {
+    method: "POST",
+    body: { email },
+  });
+}
+
+// --- Groups ---
+
+export interface AddUserToGroupInput {
+  user: { slack_user_id: string } | { email: string } | { profile_id: string };
+}
+
+export async function addUserToGroup(groupId: string, input: AddUserToGroupInput) {
+  return apiRequest<unknown>(`/groups/${groupId}/members`, {
+    method: "POST",
+    body: input as unknown as Record<string, unknown>,
+    idempotencyKey: crypto.randomUUID(),
+  });
+}
+
+// --- Messages ---
+
+export interface SendMessageInput {
+  channel: string;
+  text: string;
+  thread_ts?: string;
+}
+
+export async function sendMessage(input: SendMessageInput) {
+  return apiRequest<unknown>("/messages", {
+    method: "POST",
+    body: input as unknown as Record<string, unknown>,
+    idempotencyKey: crypto.randomUUID(),
+  });
+}
+
+// --- Search ---
+
+export interface SearchParams {
+  q: string;
+  type: "post" | "comment" | "content_resource";
+  page?: number;
+  per_page?: number;
+}
+
+export async function search(params: SearchParams) {
+  return apiRequest<{ data: unknown[]; page: number; per_page: number }>(
+    "/search",
+    { params: params as unknown as Record<string, string | number | boolean | undefined> }
+  );
+}

package/src/core/config.ts

@@ -0,0 +1,85 @@
+import Conf from "conf";
+
+interface TightknitConfig {
+  apiKey: string;
+  communityId: string;
+  defaultOutput: "json" | "table";
+}
+
+const config = new Conf<TightknitConfig>({
+  projectName: "tightknit",
+  defaults: {
+    apiKey: "",
+    communityId: "",
+    defaultOutput: "table",
+  },
+});
+
+/** Get the API key — env var takes precedence over stored config */
+export function getApiKey(): string {
+  return process.env.TIGHTKNIT_API_KEY || config.get("apiKey");
+}
+
+/** Set the API key */
+export function setApiKey(key: string): void {
+  config.set("apiKey", key);
+}
+
+/** Get the stored community ID */
+export function getCommunityId(): string {
+  return config.get("communityId");
+}
+
+/** Set the community ID */
+export function setCommunityId(id: string): void {
+  config.set("communityId", id);
+}
+
+/** Get the default output format */
+export function getDefaultOutput(): "json" | "table" {
+  return config.get("defaultOutput");
+}
+
+/** Set the default output format */
+export function setDefaultOutput(format: "json" | "table"): void {
+  config.set("defaultOutput", format);
+}
+
+/** Get a config value by key name */
+export function getConfigValue(key: string): string {
+  switch (key) {
+    case "api-key":
+      return getApiKey();
+    case "community-id":
+      return getCommunityId();
+    case "default-output":
+      return getDefaultOutput();
+    default:
+      throw new Error(`Unknown config key: ${key}. Valid keys: api-key, community-id, default-output`);
+  }
+}
+
+/** Set a config value by key name */
+export function setConfigValue(key: string, value: string): void {
+  switch (key) {
+    case "api-key":
+      setApiKey(value);
+      break;
+    case "community-id":
+      setCommunityId(value);
+      break;
+    case "default-output":
+      if (value !== "json" && value !== "table") {
+        throw new Error(`Invalid output format: ${value}. Must be "json" or "table"`);
+      }
+      setDefaultOutput(value);
+      break;
+    default:
+      throw new Error(`Unknown config key: ${key}. Valid keys: api-key, community-id, default-output`);
+  }
+}
+
+/** Get the config file path (useful for debugging) */
+export function getConfigPath(): string {
+  return config.path;
+}

package/src/core/output.ts

@@ -0,0 +1,79 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+
+interface OutputOptions {
+  json?: boolean;
+}
+
+/** Format and print data in JSON or human-readable table format */
+export function formatOutput(data: unknown, options: OutputOptions = {}): string {
+  if (options.json) {
+    return JSON.stringify(data, null, 2);
+  }
+
+  if (Array.isArray(data)) {
+    return formatTable(data);
+  }
+
+  if (typeof data === "object" && data !== null) {
+    return formatKeyValue(data as Record<string, unknown>);
+  }
+
+  return String(data);
+}
+
+/** Print formatted output to stdout */
+export function printOutput(data: unknown, options: OutputOptions = {}): void {
+  console.log(formatOutput(data, options));
+}
+
+/** Print a success message */
+export function printSuccess(message: string): void {
+  console.log(chalk.green("✓"), message);
+}
+
+/** Print an error message */
+export function printError(message: string): void {
+  console.error(chalk.red("✗"), message);
+}
+
+/** Format an array of objects as a table */
+function formatTable(rows: unknown[]): string {
+  if (rows.length === 0) {
+    return chalk.dim("No results found.");
+  }
+
+  const firstRow = rows[0] as Record<string, unknown>;
+  const keys = Object.keys(firstRow);
+
+  const table = new Table({
+    head: keys.map((k) => chalk.bold(k)),
+    style: { head: [], border: [] },
+  });
+
+  for (const row of rows) {
+    const record = row as Record<string, unknown>;
+    table.push(keys.map((k) => truncate(String(record[k] ?? ""), 50)));
+  }
+
+  return table.toString();
+}
+
+/** Format a single object as key-value pairs */
+function formatKeyValue(obj: Record<string, unknown>): string {
+  const lines: string[] = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const displayValue =
+      typeof value === "object" && value !== null
+        ? JSON.stringify(value)
+        : String(value ?? "");
+    lines.push(`${chalk.bold(key)}: ${displayValue}`);
+  }
+  return lines.join("\n");
+}
+
+/** Truncate a string to a max length */
+function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) return str;
+  return `${str.slice(0, maxLength - 1)}…`;
+}