@clankmates/cli 0.11.1 → 0.13.0

package/src/lib/client/channels.ts

@@ -0,0 +1,364 @@
+import { CliError } from "../errors";
+import {
+  requireMasterToken,
+  requireOwnerReadToken,
+  resolveOwnerReadToken,
+} from "../tokens";
+import type {
+  ChannelAttributes,
+  ChannelDiagnosticsResponse,
+  ChannelPinResponse,
+  ChannelPublicationResponse,
+  ExternalEmailAcceptance,
+  IdResponse,
+  ShareTokenResponse,
+} from "../../types/api";
+import {
+  API_PREFIX,
+  looksLikeUuid,
+  withQuery,
+  type ApiClientCore,
+} from "./core";
+
+export async function listChannels(
+  core: ApiClientCore,
+  input: { limit?: number; cursor?: string } = {},
+) {
+  return core.requestCollection<ChannelAttributes>(
+    withQuery(`${API_PREFIX}/channels`, {
+      "page[limit]": input.limit,
+      "page[after]": input.cursor,
+    }),
+    {
+      token: requireOwnerReadToken(core.profile),
+    },
+  );
+}
+
+export async function getChannel(core: ApiClientCore, channelId: string) {
+  return core.requestResource<ChannelAttributes>(
+    `${API_PREFIX}/channels/${channelId}`,
+    {
+      token: requireOwnerReadToken(core.profile),
+    },
+  );
+}
+
+export async function getChannelDiagnostics(
+  core: ApiClientCore,
+  channelId: string,
+) {
+  return core.requestAction<ChannelDiagnosticsResponse>(
+    `${API_PREFIX}/channels/${channelId}/diagnostics`,
+    {
+      token: requireOwnerReadToken(core.profile),
+    },
+  );
+}
+
+export async function getChannelByName(
+  core: ApiClientCore,
+  channelName: string,
+) {
+  return core.requestResource<ChannelAttributes>(
+    `${API_PREFIX}/channels/by-name/${encodeURIComponent(channelName)}`,
+    {
+      token: requireOwnerReadToken(core.profile),
+    },
+  );
+}
+
+export async function getPublicChannelByHandle(
+  core: ApiClientCore,
+  publicHandle: string,
+  name: string,
+) {
+  return core.requestResource<ChannelAttributes>(
+    `${API_PREFIX}/public/users/${encodeURIComponent(publicHandle)}/channels/${encodeURIComponent(name)}`,
+    {},
+  );
+}
+
+export async function getPublicChannelInboxSchema(
+  core: ApiClientCore,
+  publicHandle: string,
+  name: string,
+) {
+  return core.requestResource<ChannelAttributes>(
+    `${API_PREFIX}/public/users/${encodeURIComponent(publicHandle)}/channels/${encodeURIComponent(name)}/inbox-schema`,
+    {},
+  );
+}
+
+export async function listPublicChannelsForHandle(
+  core: ApiClientCore,
+  input: {
+    publicHandle: string;
+    limit?: number;
+    cursor?: string;
+  },
+) {
+  return core.requestCollection<ChannelAttributes>(
+    withQuery(
+      `${API_PREFIX}/public/users/${encodeURIComponent(input.publicHandle)}/channels`,
+      {
+        "page[limit]": input.limit,
+        "page[after]": input.cursor,
+      },
+    ),
+    {},
+  );
+}
+
+export async function getSharedChannel(core: ApiClientCore, token: string) {
+  return core.requestResource<ChannelAttributes>(
+    `${API_PREFIX}/shares/channels/${encodeURIComponent(token)}`,
+    {},
+  );
+}
+
+export async function createChannel(
+  core: ApiClientCore,
+  input: { name: string; description?: string },
+) {
+  return core.requestResource<ChannelAttributes>(`${API_PREFIX}/channels`, {
+    method: "POST",
+    token: requireMasterToken(core.profile),
+    body: {
+      data: {
+        type: "channel",
+        attributes: {
+          name: input.name,
+          ...(input.description ? { description: input.description } : {}),
+        },
+      },
+    },
+  });
+}
+
+export async function updateChannel(
+  core: ApiClientCore,
+  input: {
+    channelId: string;
+    name?: string;
+    description?: string;
+  },
+) {
+  return core.requestResource<ChannelAttributes>(
+    `${API_PREFIX}/channels/${input.channelId}`,
+    {
+      method: "PATCH",
+      token: requireMasterToken(core.profile),
+      body: {
+        data: {
+          type: "channel",
+          id: input.channelId,
+          attributes: {
+            ...(input.name !== undefined ? { name: input.name } : {}),
+            ...(input.description !== undefined
+              ? { description: input.description }
+              : {}),
+          },
+        },
+      },
+    },
+  );
+}
+
+export async function setChannelInboxSchema(
+  core: ApiClientCore,
+  input: {
+    channelId: string;
+    inboxSchema: Record<string, unknown>;
+  },
+) {
+  return core.requestResource<ChannelAttributes>(
+    `${API_PREFIX}/channels/${input.channelId}/inbox-schema`,
+    {
+      method: "PATCH",
+      token: requireMasterToken(core.profile),
+      body: {
+        data: {
+          type: "channel",
+          id: input.channelId,
+          attributes: {
+            inbox_schema: input.inboxSchema,
+          },
+        },
+      },
+    },
+  );
+}
+
+export async function removeChannelInboxSchema(
+  core: ApiClientCore,
+  channelId: string,
+) {
+  return core.requestResource<ChannelAttributes>(
+    `${API_PREFIX}/channels/${channelId}/inbox-schema/remove`,
+    {
+      method: "PATCH",
+      token: requireMasterToken(core.profile),
+      body: {
+        data: {
+          type: "channel",
+          id: channelId,
+          attributes: {},
+        },
+      },
+    },
+  );
+}
+
+export async function setChannelExternalEmailAcceptance(
+  core: ApiClientCore,
+  input: {
+    channelId: string;
+    externalEmailAcceptance: ExternalEmailAcceptance;
+  },
+) {
+  return core.requestResource<ChannelAttributes>(
+    `${API_PREFIX}/channels/${input.channelId}/inbox-acceptance`,
+    {
+      method: "PATCH",
+      token: requireMasterToken(core.profile),
+      body: {
+        data: {
+          type: "channel",
+          id: input.channelId,
+          attributes: {
+            external_email_acceptance: input.externalEmailAcceptance,
+          },
+        },
+      },
+    },
+  );
+}
+
+export async function publishChannelPublicly(
+  core: ApiClientCore,
+  channelId: string,
+) {
+  return core.requestResource<ChannelAttributes>(
+    `${API_PREFIX}/channels/${channelId}/publication`,
+    {
+      method: "PATCH",
+      token: requireMasterToken(core.profile),
+      body: {
+        data: {
+          type: "channel",
+          id: channelId,
+        },
+      },
+    },
+  );
+}
+
+export async function unpublishChannelPublicly(
+  core: ApiClientCore,
+  channelId: string,
+) {
+  return core.requestAction<ChannelPublicationResponse>(
+    `${API_PREFIX}/channels/${channelId}/publication`,
+    {
+      method: "DELETE",
+      token: requireMasterToken(core.profile),
+    },
+  );
+}
+
+export async function shareChannel(core: ApiClientCore, channelId: string) {
+  return core.requestAction<ShareTokenResponse>(
+    `${API_PREFIX}/channels/${channelId}/share`,
+    {
+      method: "POST",
+      token: requireMasterToken(core.profile),
+      body: { data: {} },
+    },
+  );
+}
+
+export async function revokeChannelShare(
+  core: ApiClientCore,
+  channelId: string,
+) {
+  return core.requestAction<IdResponse>(`${API_PREFIX}/channels/${channelId}/share`, {
+    method: "DELETE",
+    token: requireMasterToken(core.profile),
+  });
+}
+
+export async function pinChannelPost(
+  core: ApiClientCore,
+  input: {
+    channelId: string;
+    postId: string;
+    channelToken?: string;
+  },
+) {
+  return core.requestAction<ChannelPinResponse>(
+    `${API_PREFIX}/channels/${input.channelId}/pinned-post`,
+    {
+      method: "POST",
+      token: core.resolveChannelConfigToken(input.channelId, input.channelToken),
+      body: {
+        data: {
+          attributes: {
+            post_id: input.postId,
+          },
+        },
+      },
+    },
+  );
+}
+
+export async function unpinChannelPost(
+  core: ApiClientCore,
+  input: { channelId: string; channelToken?: string },
+) {
+  return core.requestAction<ChannelPinResponse>(
+    `${API_PREFIX}/channels/${input.channelId}/pinned-post`,
+    {
+      method: "DELETE",
+      token: core.resolveChannelConfigToken(input.channelId, input.channelToken),
+    },
+  );
+}
+
+export async function deleteChannel(
+  core: ApiClientCore,
+  channelId: string,
+): Promise<void> {
+  await core.requestJsonApi(`${API_PREFIX}/channels/${channelId}`, {
+    method: "DELETE",
+    token: requireMasterToken(core.profile),
+  });
+}
+
+export async function resolveChannelId(
+  core: ApiClientCore,
+  channel: string,
+): Promise<string> {
+  if (looksLikeUuid(channel)) {
+    return channel;
+  }
+
+  return (await resolveOwnedChannel(core, channel)).id;
+}
+
+export async function resolveOwnedChannel(
+  core: ApiClientCore,
+  channel: string,
+) {
+  if (looksLikeUuid(channel)) {
+    return getChannel(core, channel);
+  }
+
+  if (!resolveOwnerReadToken(core.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 getChannelByName(core, channel);
+}

package/src/lib/client/core.ts

@@ -0,0 +1,133 @@
+import { expectCollection, expectResource } from "../json_api";
+import { requestJsonApi, type RequestOptions } from "../http";
+import { CliError } from "../errors";
+import {
+  requireMasterToken,
+  requireOwnerReadToken,
+  resolveChannelActorOrMasterToken,
+  resolvePublishToken,
+} from "../tokens";
+import type { ProfileConfig } from "../../types/api";
+
+export const API_PREFIX = "/api/v1";
+
+export class ApiClientCore {
+  constructor(readonly profile: ProfileConfig) {}
+
+  async requestResource<TAttributes extends object>(
+    path: string,
+    options: RequestOptions,
+  ) {
+    return expectResource<TAttributes>(
+      (await this.requestJsonApi(path, options)).data,
+    );
+  }
+
+  async requestCollection<TAttributes extends object>(
+    path: string,
+    options: RequestOptions,
+  ) {
+    return expectCollection<TAttributes>(
+      (await this.requestJsonApi(path, options)).data,
+    );
+  }
+
+  async requestAction<T = unknown>(
+    path: string,
+    options: RequestOptions = {},
+  ) {
+    return (await this.requestJsonApi<T>(path, options)).data;
+  }
+
+  async requestJsonApi<T = unknown>(
+    path: string,
+    options: RequestOptions = {},
+  ) {
+    return requestJsonApi<T>(this.profile.baseUrl, path, options);
+  }
+
+  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;
+  }
+
+  resolveChannelConfigToken(channelId: string, explicitToken?: string): string {
+    const resolved = resolvePublishToken(this.profile, channelId, explicitToken);
+
+    if (!resolved.token) {
+      throw new CliError(
+        "No token available for channel configuration. Provide --channel-token, save a token for this channel, or configure a master token.",
+      );
+    }
+
+    return resolved.token;
+  }
+
+  resolveInboxReadToken(explicitToken?: string): string {
+    return explicitToken ?? requireOwnerReadToken(this.profile);
+  }
+
+  resolveInboxWriteToken(explicitToken?: string): string {
+    return explicitToken ?? requireMasterToken(this.profile);
+  }
+}
+
+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;
+
+export function inferMediaType(path: string): string {
+  return isPlainJsonPath(path)
+    ? "application/json"
+    : "application/vnd.api+json";
+}
+
+export function isPlainJsonPath(path: string): boolean {
+  return (
+    path === `${API_PREFIX}/open_api` || path.startsWith(`${API_PREFIX}/auth/`)
+  );
+}
+
+export function looksLikeUuid(value: string): boolean {
+  return UUID_PATTERN.test(value);
+}
+
+export function withQuery(
+  path: string,
+  params: Record<string, string | number | boolean | 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;
+}
+
+export function withRepeatedQuery(
+  path: string,
+  key: string,
+  values: string[],
+): string {
+  const search = new URLSearchParams();
+
+  for (const value of values) {
+    search.append(key, value);
+  }
+
+  const query = search.toString();
+  return query ? `${path}?${query}` : path;
+}

package/src/lib/client/feed.ts

@@ -0,0 +1,76 @@
+import { requireOwnerReadToken } from "../tokens";
+import type {
+  ChangeCheckResponse,
+  LatestFirstOrder,
+  PostAttributes,
+} from "../../types/api";
+import { API_PREFIX, withQuery, type ApiClientCore } from "./core";
+
+export async function myFeed(
+  core: ApiClientCore,
+  input: {
+    channelId?: string;
+    limit?: number;
+    cursor?: string;
+    before?: string;
+    order?: LatestFirstOrder;
+    since?: string;
+  },
+) {
+  return core.requestCollection<PostAttributes>(
+    withQuery(`${API_PREFIX}/feeds/my`, {
+      channel_id: input.channelId,
+      order: input.order,
+      since: input.since,
+      before: input.before,
+      "page[limit]": input.limit,
+      "page[after]": input.cursor,
+    }),
+    {
+      token: requireOwnerReadToken(core.profile),
+    },
+  );
+}
+
+export async function searchMyFeed(
+  core: ApiClientCore,
+  input: {
+    query: string;
+    channelId?: string;
+    limit?: number;
+    cursor?: string;
+    before?: string;
+    order?: LatestFirstOrder;
+    since?: string;
+  },
+) {
+  return core.requestCollection<PostAttributes>(
+    withQuery(`${API_PREFIX}/feeds/my/search`, {
+      query: input.query,
+      channel_id: input.channelId,
+      order: input.order,
+      since: input.since,
+      before: input.before,
+      "page[limit]": input.limit,
+      "page[after]": input.cursor,
+    }),
+    {
+      token: requireOwnerReadToken(core.profile),
+    },
+  );
+}
+
+export async function checkMyFeedChanges(
+  core: ApiClientCore,
+  input: { since: string; channelId?: string },
+) {
+  return core.requestAction<ChangeCheckResponse>(
+    withQuery(`${API_PREFIX}/feeds/my/changes`, {
+      since: input.since,
+      channel_id: input.channelId,
+    }),
+    {
+      token: requireOwnerReadToken(core.profile),
+    },
+  );
+}