@clankmates/cli 0.1.0

package/src/lib/body-input.ts

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+
+import { booleanFlag, stringFlag, type ParsedArgs } from "./args";
+import { CliError } from "./errors";
+
+export interface ResolveBodyInputOptions {
+  flags: ParsedArgs["flags"];
+  requireBody?: boolean;
+  readFileText?: (path: string) => Promise<string>;
+  readStdinText?: () => Promise<string>;
+}
+
+export async function resolveBodyInput({
+  flags,
+  requireBody = false,
+  readFileText = (path) => readFile(path, "utf8"),
+  readStdinText = () => readStdin()
+}: ResolveBodyInputOptions): Promise<string | undefined> {
+  const inlineBody = stringFlag(flags, "body");
+  const bodyFile = stringFlag(flags, "bodyFile");
+  const useStdin = booleanFlag(flags, "stdin");
+  const providedCount = [inlineBody !== undefined, bodyFile !== undefined, useStdin].filter(Boolean).length;
+
+  if (requireBody && providedCount === 0) {
+    throw new CliError("Provide exactly one of `--body`, `--body-file`, or `--stdin`", 2);
+  }
+
+  if (providedCount > 1) {
+    throw new CliError("Use only one of `--body`, `--body-file`, or `--stdin`", 2);
+  }
+
+  if (inlineBody !== undefined) {
+    return inlineBody;
+  }
+
+  if (bodyFile !== undefined) {
+    return readFileText(bodyFile);
+  }
+
+  if (useStdin) {
+    return readStdinText();
+  }
+
+  return undefined;
+}
+
+export async function readStdin(stdin: AsyncIterable<unknown> = process.stdin): Promise<string> {
+  let buffer = "";
+
+  for await (const chunk of stdin) {
+    buffer += typeof chunk === "string" ? chunk : Buffer.from(chunk as ArrayBufferLike).toString("utf8");
+  }
+
+  return buffer;
+}

package/src/lib/client.ts

@@ -0,0 +1,372 @@
+import { expectCollection, expectResource } from "./json_api";
+import { requestJson, requestJsonApi, type RequestOptions } from "./http";
+import { CliError } from "./errors";
+import {
+  requireOwnerReadToken,
+  requireMasterToken,
+  resolveChannelActorOrMasterToken,
+  resolveMasterToken,
+  resolveOwnerReadToken,
+  resolvePublishToken,
+} from "./tokens";
+import type {
+  WhoamiResponse,
+  ChannelAttributes,
+  PostAttributes,
+  ProfileConfig,
+  RotateTokenResponse,
+} from "../types/api";
+
+export class ClankmatesClient {
+  constructor(private readonly profile: ProfileConfig) {}
+
+  async validateMasterToken(token: string): Promise<void> {
+    const response = await this.whoami(token);
+
+    if (
+      response.actor.type !== "user" ||
+      response.actor.scope === "read_only"
+    ) {
+      throw new CliError("Provided token is not a master token.");
+    }
+  }
+
+  async validateReadOnlyToken(token: string): Promise<void> {
+    const response = await this.whoami(token);
+
+    if (
+      response.actor.type !== "user" ||
+      response.actor.scope !== "read_only"
+    ) {
+      throw new CliError("Provided token is not a read-only token.");
+    }
+  }
+
+  async whoami(
+    token = requireOwnerReadToken(this.profile),
+  ): Promise<WhoamiResponse> {
+    return (
+      await requestJson<WhoamiResponse>(
+        this.profile.baseUrl,
+        `${API_PREFIX}/auth/whoami`,
+        { token },
+      )
+    ).data;
+  }
+
+  async listChannels() {
+    return this.requestCollection<ChannelAttributes>(`${API_PREFIX}/channels`, {
+      token: requireOwnerReadToken(this.profile),
+    });
+  }
+
+  async getChannel(channelId: string) {
+    return this.requestResource<ChannelAttributes>(
+      `${API_PREFIX}/channels/${channelId}`,
+      {
+        token: requireOwnerReadToken(this.profile),
+      },
+    );
+  }
+
+  async getChannelByName(channelName: string) {
+    return this.requestResource<ChannelAttributes>(
+      `${API_PREFIX}/channels/by-name/${encodeURIComponent(channelName)}`,
+      {
+        token: requireOwnerReadToken(this.profile),
+      },
+    );
+  }
+
+  async createChannel(input: { name: string; description?: string }) {
+    return this.requestResource<ChannelAttributes>(`${API_PREFIX}/channels`, {
+      method: "POST",
+      token: requireMasterToken(this.profile),
+      body: {
+        data: {
+          type: "channel",
+          attributes: {
+            name: input.name,
+            ...(input.description ? { description: input.description } : {}),
+          },
+        },
+      },
+    });
+  }
+
+  async updateChannel(input: {
+    channelId: string;
+    name?: string;
+    description?: string;
+  }) {
+    return this.requestResource<ChannelAttributes>(
+      `${API_PREFIX}/channels/${input.channelId}`,
+      {
+        method: "PATCH",
+        token: requireMasterToken(this.profile),
+        body: {
+          data: {
+            type: "channel",
+            id: input.channelId,
+            attributes: {
+              ...(input.name !== undefined ? { name: input.name } : {}),
+              ...(input.description !== undefined
+                ? { description: input.description }
+                : {}),
+            },
+          },
+        },
+      },
+    );
+  }
+
+  async deleteChannel(channelId: string): Promise<void> {
+    await this.requestJsonApi(`${API_PREFIX}/channels/${channelId}`, {
+      method: "DELETE",
+      token: requireMasterToken(this.profile),
+    });
+  }
+
+  async rotateChannelToken(channelId: string): Promise<RotateTokenResponse> {
+    return (
+      await this.requestJsonApi<RotateTokenResponse>(
+        `${API_PREFIX}/channels/${channelId}/token/rotate`,
+        {
+          method: "POST",
+          token: requireMasterToken(this.profile),
+          body: {},
+        },
+      )
+    ).data;
+  }
+
+  async publishPost(input: {
+    channelId: string;
+    body: string;
+    channelToken?: string;
+  }) {
+    const resolved = resolvePublishToken(
+      this.profile,
+      input.channelId,
+      input.channelToken,
+    );
+
+    if (!resolved.token) {
+      throw new CliError(
+        `No publish token available for channel ${input.channelId}. Provide --channel-token, set channel token env vars, save a channel token, or configure a master token.`,
+      );
+    }
+
+    return this.requestResource<PostAttributes>(
+      `${API_PREFIX}/channels/${input.channelId}/posts`,
+      {
+        method: "POST",
+        token: resolved.token,
+        body: {
+          data: {
+            type: "post",
+            attributes: {
+              body: input.body,
+            },
+          },
+        },
+      },
+    );
+  }
+
+  async listChannelPosts(input: {
+    channelId: string;
+    limit?: number;
+    cursor?: string;
+  }) {
+    return this.requestCollection<PostAttributes>(
+      withQuery(`${API_PREFIX}/channels/${input.channelId}/posts`, {
+        "page[limit]": input.limit,
+        "page[after]": input.cursor,
+      }),
+      {
+        token: requireOwnerReadToken(this.profile),
+      },
+    );
+  }
+
+  async getPost(postId: string) {
+    return this.requestResource<PostAttributes>(
+      `${API_PREFIX}/posts/${postId}`,
+      {
+        token: requireOwnerReadToken(this.profile),
+      },
+    );
+  }
+
+  async editPost(input: {
+    postId: string;
+    body: string;
+    channelToken?: string;
+  }) {
+    const token = this.resolvePostLifecycleToken(input.channelToken);
+
+    return this.requestResource<PostAttributes>(
+      `${API_PREFIX}/posts/${input.postId}`,
+      {
+        method: "PATCH",
+        token,
+        body: {
+          data: {
+            type: "post",
+            id: input.postId,
+            attributes: {
+              body: input.body,
+            },
+          },
+        },
+      },
+    );
+  }
+
+  async deletePost(input: {
+    postId: string;
+    channelToken?: string;
+  }): Promise<void> {
+    const token = this.resolvePostLifecycleToken(input.channelToken);
+
+    await this.requestJsonApi(`${API_PREFIX}/posts/${input.postId}`, {
+      method: "DELETE",
+      token,
+    });
+  }
+
+  async myFeed(input: { channelId?: string; limit?: number; cursor?: string }) {
+    return this.requestCollection<PostAttributes>(
+      withQuery(`${API_PREFIX}/feeds/my`, {
+        channel_id: input.channelId,
+        "page[limit]": input.limit,
+        "page[after]": input.cursor,
+      }),
+      {
+        token: requireOwnerReadToken(this.profile),
+      },
+    );
+  }
+
+  async fetchOpenApi(): Promise<unknown> {
+    return (await requestJson(this.profile.baseUrl, `${API_PREFIX}/open_api`))
+      .data;
+  }
+
+  async apiRequest(input: {
+    method: string;
+    path: string;
+    body?: string;
+    channelToken?: string;
+  }): Promise<unknown> {
+    return (
+      await requestJson(this.profile.baseUrl, input.path, {
+        method: input.method,
+        token: input.channelToken ?? resolveMasterToken(this.profile).token,
+        rawBody: input.body,
+        accept: inferMediaType(input.path),
+        contentType:
+          input.body === undefined ? undefined : inferMediaType(input.path),
+      })
+    ).data;
+  }
+
+  private async requestResource<TAttributes extends object>(
+    path: string,
+    options: RequestOptions,
+  ) {
+    return expectResource<TAttributes>(
+      (await this.requestJsonApi(path, options)).data,
+    );
+  }
+
+  private async requestCollection<TAttributes extends object>(
+    path: string,
+    options: RequestOptions,
+  ) {
+    return expectCollection<TAttributes>(
+      (await this.requestJsonApi(path, options)).data,
+    );
+  }
+
+  private async requestJsonApi<T = unknown>(
+    path: string,
+    options: RequestOptions = {},
+  ) {
+    return requestJsonApi<T>(this.profile.baseUrl, path, options);
+  }
+
+  async resolveChannelId(channel: string): Promise<string> {
+    if (looksLikeUuid(channel)) {
+      return channel;
+    }
+
+    return (await this.resolveOwnedChannel(channel)).id;
+  }
+
+  async resolveOwnedChannel(channel: string) {
+    if (looksLikeUuid(channel)) {
+      return this.getChannel(channel);
+    }
+
+    if (!resolveOwnerReadToken(this.profile).token) {
+      throw new CliError(
+        `Resolving channel name "${channel}" requires an owner read token. Use the channel UUID or configure a read-only or master token.`,
+      );
+    }
+
+    return this.getChannelByName(channel);
+  }
+
+  private resolvePostLifecycleToken(explicitToken?: string): string {
+    const resolved = resolveChannelActorOrMasterToken(
+      this.profile,
+      explicitToken,
+    );
+
+    if (!resolved.token) {
+      throw new CliError(
+        "No token available for post edit/delete. Provide --channel-token, set CLANKMATES_CHANNEL_TOKEN, configure a single saved channel token, or configure a master token.",
+      );
+    }
+
+    return resolved.token;
+  }
+}
+
+const API_PREFIX = "/api/v1";
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function inferMediaType(path: string): string {
+  return isPlainJsonPath(path)
+    ? "application/json"
+    : "application/vnd.api+json";
+}
+
+function isPlainJsonPath(path: string): boolean {
+  return (
+    path === `${API_PREFIX}/open_api` || path.startsWith(`${API_PREFIX}/auth/`)
+  );
+}
+
+function looksLikeUuid(value: string): boolean {
+  return UUID_PATTERN.test(value);
+}
+
+function withQuery(
+  path: string,
+  params: Record<string, string | number | undefined>,
+): string {
+  const search = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined) {
+      search.set(key, String(value));
+    }
+  }
+
+  const query = search.toString();
+  return query ? `${path}?${query}` : path;
+}

package/src/lib/config.ts

@@ -0,0 +1,219 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { CliError } from "./errors";
+import { getConfigPath } from "./paths";
+import type { ConfigFile, OutputMode, ProfileConfig } from "../types/api";
+
+const DEFAULT_BASE_URL = "https://clankmates.com";
+const DEFAULT_PROFILE = "default";
+
+function defaultProfile(baseUrl?: string): ProfileConfig {
+  return {
+    baseUrl: resolveBaseUrl(baseUrl),
+    output: "table",
+    channelTokens: {}
+  };
+}
+
+function defaultConfig(baseUrl?: string): ConfigFile {
+  return {
+    version: 1,
+    activeProfile: DEFAULT_PROFILE,
+    profiles: {
+      [DEFAULT_PROFILE]: defaultProfile(baseUrl)
+    }
+  };
+}
+
+function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/\/+$/, "");
+}
+
+export function resolveBaseUrl(baseUrl?: string, fallback = DEFAULT_BASE_URL): string {
+  return normalizeBaseUrl(baseUrl ?? process.env.CLANKMATES_BASE_URL ?? fallback);
+}
+
+export async function loadConfig(configPath = getConfigPath()): Promise<ConfigFile> {
+  try {
+    const raw = await readFile(configPath, "utf8");
+    const parsed = JSON.parse(raw) as ConfigFile;
+
+    if (parsed.version !== 1 || typeof parsed.activeProfile !== "string" || !parsed.profiles) {
+      throw new CliError(`Unsupported config format in ${configPath}`);
+    }
+
+    return parsed;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return defaultConfig();
+    }
+
+    if (error instanceof CliError) {
+      throw error;
+    }
+
+    throw new CliError(`Failed to read config from ${configPath}: ${(error as Error).message}`);
+  }
+}
+
+export async function saveConfig(config: ConfigFile, configPath = getConfigPath()): Promise<void> {
+  await mkdir(path.dirname(configPath), { recursive: true });
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+export async function updateConfig(
+  mutate: (config: ConfigFile) => void,
+  configPath = getConfigPath()
+): Promise<ConfigFile> {
+  const config = await loadConfig(configPath);
+  mutate(config);
+  await saveConfig(config, configPath);
+  return config;
+}
+
+export async function updateProfile(
+  profileName: string,
+  mutate: (profile: ProfileConfig, config: ConfigFile) => void,
+  configPath = getConfigPath()
+): Promise<ConfigFile> {
+  return updateConfig((config) => {
+    config.profiles[profileName] ??= defaultProfile();
+    mutate(config.profiles[profileName], config);
+    config.profiles[profileName].baseUrl = normalizeBaseUrl(config.profiles[profileName].baseUrl);
+  }, configPath);
+}
+
+export async function ensureConfig(configPath = getConfigPath(), baseUrl?: string): Promise<ConfigFile> {
+  return updateConfig((config) => {
+    config.profiles[config.activeProfile] ??= defaultProfile(baseUrl);
+    const activeProfile = config.profiles[config.activeProfile]!;
+
+    if (baseUrl) {
+      activeProfile.baseUrl = normalizeBaseUrl(baseUrl);
+    }
+  }, configPath);
+}
+
+export async function ensureProfile(
+  profileName: string,
+  configPath = getConfigPath(),
+  baseUrl?: string
+): Promise<ConfigFile> {
+  return updateProfile(
+    profileName,
+    (profile) => {
+      if (baseUrl) {
+        profile.baseUrl = baseUrl;
+      }
+    },
+    configPath
+  );
+}
+
+export function resolveProfileName(config: ConfigFile, profileName?: string): string {
+  return profileName ?? process.env.CLANKMATES_PROFILE ?? config.activeProfile;
+}
+
+export function resolveProfile(config: ConfigFile, profileName?: string): { profileName: string; profile: ProfileConfig } {
+  const resolvedName = resolveProfileName(config, profileName);
+  const profile = config.profiles[resolvedName];
+
+  if (!profile) {
+    throw new CliError(`Unknown profile "${resolvedName}"`);
+  }
+
+  return {
+    profileName: resolvedName,
+    profile: {
+      ...profile,
+      baseUrl: resolveBaseUrl(undefined, profile.baseUrl)
+    }
+  };
+}
+
+export async function setActiveProfile(profileName: string, configPath = getConfigPath()): Promise<ConfigFile> {
+  return updateProfile(
+    profileName,
+    (_profile, config) => {
+      config.activeProfile = profileName;
+    },
+    configPath
+  );
+}
+
+export async function setProfileBaseUrl(
+  profileName: string,
+  baseUrl: string,
+  configPath = getConfigPath()
+): Promise<ConfigFile> {
+  return updateProfile(
+    profileName,
+    (profile) => {
+      profile.baseUrl = baseUrl;
+    },
+    configPath
+  );
+}
+
+export async function setProfileOutput(
+  profileName: string,
+  output: OutputMode,
+  configPath = getConfigPath()
+): Promise<ConfigFile> {
+  return updateProfile(
+    profileName,
+    (profile) => {
+      profile.output = output;
+    },
+    configPath
+  );
+}
+
+export async function setMasterToken(
+  profileName: string,
+  token: string | undefined,
+  configPath = getConfigPath()
+): Promise<ConfigFile> {
+  return updateProfile(
+    profileName,
+    (profile) => {
+      profile.masterToken = token;
+    },
+    configPath
+  );
+}
+
+export async function setReadOnlyToken(
+  profileName: string,
+  token: string | undefined,
+  configPath = getConfigPath()
+): Promise<ConfigFile> {
+  return updateProfile(
+    profileName,
+    (profile) => {
+      profile.readOnlyToken = token;
+    },
+    configPath
+  );
+}
+
+export async function storeChannelToken(
+  profileName: string,
+  channelId: string,
+  token: string,
+  configPath = getConfigPath()
+): Promise<ConfigFile> {
+  return updateProfile(
+    profileName,
+    (profile) => {
+      profile.channelTokens[channelId] = {
+        token,
+        updatedAt: new Date().toISOString()
+      };
+    },
+    configPath
+  );
+}
+
+export { DEFAULT_BASE_URL };

package/src/lib/context.ts

@@ -0,0 +1,39 @@
+import { loadConfig, resolveProfile } from "./config";
+import { booleanFlag, stringFlag, type ParsedArgs } from "./args";
+import { getConfigPath } from "./paths";
+import { ClankmatesClient } from "./client";
+import type { Io } from "./output";
+import type { ConfigFile, OutputMode, ProfileConfig } from "../types/api";
+
+export interface CommandContext {
+  config: ConfigFile;
+  configPath: string;
+  profileName: string;
+  profile: ProfileConfig;
+  outputMode: OutputMode;
+  client: ClankmatesClient;
+  io: Io;
+}
+
+export async function createCommandContext(args: ParsedArgs, io: Io): Promise<CommandContext> {
+  const configPath = getConfigPath();
+  const config = await loadConfig(configPath);
+  const { profileName, profile } = resolveProfile(config, stringFlag(args.flags, "profile"));
+
+  return {
+    config,
+    configPath,
+    profileName,
+    profile,
+    outputMode: resolveOutputMode(profile, args.flags),
+    client: new ClankmatesClient(profile),
+    io
+  };
+}
+
+export function resolveOutputMode(
+  profile: Pick<ProfileConfig, "output">,
+  flags: ParsedArgs["flags"]
+): OutputMode {
+  return booleanFlag(flags, "json") ? "json" : profile.output;
+}

package/src/lib/errors.ts

@@ -0,0 +1,17 @@
+export class CliError extends Error {
+  readonly exitCode: number;
+
+  constructor(message: string, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}
+
+export function assertPresent(value: string | undefined, message: string): string {
+  if (!value) {
+    throw new CliError(message, 2);
+  }
+
+  return value;
+}