@clankmates/cli 0.1.1 → 0.3.0

package/src/commands/user.ts

@@ -0,0 +1,52 @@
+import { requiredPositional, type ParsedArgs } from "../lib/args";
+import { createCommandContext } from "../lib/context";
+import { CliError } from "../lib/errors";
+import { printValue, type Io } from "../lib/output";
+
+export async function runUserCommand(args: ParsedArgs, io: Io): Promise<void> {
+  const subcommand = args.positionals[0];
+  const context = await createCommandContext(args, io);
+
+  switch (subcommand) {
+    case "get": {
+      const user = await context.client.getUserByPublicHandle(
+        requiredPositional(args.positionals, 1, "Missing public handle"),
+      );
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? user
+          : {
+              id: user.id,
+              email: user.attributes.email,
+              publicHandle: user.attributes.public_handle ?? "",
+            },
+      );
+      return;
+    }
+
+    case "claim-handle": {
+      const user = await context.client.claimPublicHandle(
+        requiredPositional(args.positionals, 1, "Missing public handle"),
+      );
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? user
+          : {
+              id: user.id,
+              email: user.attributes.email,
+              publicHandle: user.attributes.public_handle ?? "",
+            },
+      );
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown user subcommand", 2);
+  }
+}

package/src/lib/args.ts

@@ -15,6 +15,7 @@ const CLI_OPTIONS = {
   "master-token": { type: "string" },
   readOnlyToken: { type: "string" },
   "read-only-token": { type: "string" },
+  scope: { type: "string" },
   name: { type: "string" },
   description: { type: "string" },
   save: { type: "boolean" },

package/src/lib/client.ts

@@ -2,24 +2,47 @@ import { expectCollection, expectResource } from "./json_api";
 import { requestJson, requestJsonApi, type RequestOptions } from "./http";
 import { CliError } from "./errors";
 import {
-  requireOwnerReadToken,
   requireMasterToken,
+  requireOwnerReadToken,
   resolveChannelActorOrMasterToken,
   resolveMasterToken,
   resolveOwnerReadToken,
   resolvePublishToken,
 } from "./tokens";
 import type {
-  WhoamiResponse,
+  AccessKeyAttributes,
+  AccessKeyIssueResponse,
+  AccessKeyRevokeResponse,
+  AccessKeyScope,
   ChannelAttributes,
+  ChannelKeyAttributes,
+  ChannelKeyIssueResponse,
+  ChannelKeyRevokeResponse,
+  ChannelPublicationResponse,
+  IdResponse,
   PostAttributes,
   ProfileConfig,
-  RotateTokenResponse,
+  ShareTokenResponse,
+  UserAttributes,
+  WhoamiResponse,
 } from "../types/api";
 
 export class ClankmatesClient {
   constructor(private readonly profile: ProfileConfig) {}
 
+  async canAuthenticate(token: string): Promise<boolean> {
+    try {
+      await this.whoami(token);
+      return true;
+    } catch (error) {
+      if (isUnauthorizedCliError(error)) {
+        return false;
+      }
+
+      throw error;
+    }
+  }
+
   async validateMasterToken(token: string): Promise<void> {
     const response = await this.whoami(token);
 
@@ -54,12 +77,76 @@ export class ClankmatesClient {
     ).data;
   }
 
-  async listChannels() {
-    return this.requestCollection<ChannelAttributes>(`${API_PREFIX}/channels`, {
+  async listAccessKeys(scope?: AccessKeyScope) {
+    const path = scope
+      ? `${API_PREFIX}/me/access-keys/scopes/${encodeURIComponent(scope)}`
+      : `${API_PREFIX}/me/access-keys`;
+
+    return this.requestCollection<AccessKeyAttributes>(path, {
       token: requireOwnerReadToken(this.profile),
     });
   }
 
+  async issueAccessKey(input: { scope: AccessKeyScope; name: string }) {
+    return this.requestAction<AccessKeyIssueResponse>(
+      `${API_PREFIX}/me/access-keys`,
+      {
+        method: "POST",
+        token: requireMasterToken(this.profile),
+        body: {
+          data: {
+            scope: input.scope,
+            name: input.name,
+          },
+        },
+      },
+    );
+  }
+
+  async revokeAccessKey(id: string) {
+    return this.requestAction<AccessKeyRevokeResponse>(
+      `${API_PREFIX}/me/access-keys/${id}`,
+      {
+        method: "DELETE",
+        token: requireMasterToken(this.profile),
+      },
+    );
+  }
+
+  async claimPublicHandle(publicHandle: string) {
+    return this.requestResource<UserAttributes>(`${API_PREFIX}/me/public-handle`, {
+      method: "PATCH",
+      token: requireMasterToken(this.profile),
+      body: {
+        data: {
+          type: "user",
+          attributes: {
+            public_handle: publicHandle,
+          },
+        },
+      },
+    });
+  }
+
+  async getUserByPublicHandle(publicHandle: string) {
+    return this.requestResource<UserAttributes>(
+      `${API_PREFIX}/public/users/${encodeURIComponent(publicHandle)}`,
+      {},
+    );
+  }
+
+  async listChannels(input: { limit?: number; cursor?: string } = {}) {
+    return this.requestCollection<ChannelAttributes>(
+      withQuery(`${API_PREFIX}/channels`, {
+        "page[limit]": input.limit,
+        "page[after]": input.cursor,
+      }),
+      {
+        token: requireOwnerReadToken(this.profile),
+      },
+    );
+  }
+
   async getChannel(channelId: string) {
     return this.requestResource<ChannelAttributes>(
       `${API_PREFIX}/channels/${channelId}`,
@@ -78,6 +165,37 @@ export class ClankmatesClient {
     );
   }
 
+  async getPublicChannelByHandle(handle: string, name: string) {
+    return this.requestResource<ChannelAttributes>(
+      `${API_PREFIX}/public/users/${encodeURIComponent(handle)}/channels/${encodeURIComponent(name)}`,
+      {},
+    );
+  }
+
+  async listPublicChannelsForHandle(input: {
+    handle: string;
+    limit?: number;
+    cursor?: string;
+  }) {
+    return this.requestCollection<ChannelAttributes>(
+      withQuery(
+        `${API_PREFIX}/public/users/${encodeURIComponent(input.handle)}/channels`,
+        {
+          "page[limit]": input.limit,
+          "page[after]": input.cursor,
+        },
+      ),
+      {},
+    );
+  }
+
+  async getSharedChannel(token: string) {
+    return this.requestResource<ChannelAttributes>(
+      `${API_PREFIX}/shares/channels/${encodeURIComponent(token)}`,
+      {},
+    );
+  }
+
   async createChannel(input: { name: string; description?: string }) {
     return this.requestResource<ChannelAttributes>(`${API_PREFIX}/channels`, {
       method: "POST",
@@ -120,6 +238,50 @@ export class ClankmatesClient {
     );
   }
 
+  async publishChannelPublicly(channelId: string) {
+    return this.requestResource<ChannelAttributes>(
+      `${API_PREFIX}/channels/${channelId}/publication`,
+      {
+        method: "PATCH",
+        token: requireMasterToken(this.profile),
+        body: {
+          data: {
+            type: "channel",
+            id: channelId,
+          },
+        },
+      },
+    );
+  }
+
+  async unpublishChannelPublicly(channelId: string) {
+    return this.requestAction<ChannelPublicationResponse>(
+      `${API_PREFIX}/channels/${channelId}/publication`,
+      {
+        method: "DELETE",
+        token: requireMasterToken(this.profile),
+      },
+    );
+  }
+
+  async shareChannel(channelId: string) {
+    return this.requestAction<ShareTokenResponse>(
+      `${API_PREFIX}/channels/${channelId}/share`,
+      {
+        method: "POST",
+        token: requireMasterToken(this.profile),
+        body: { data: {} },
+      },
+    );
+  }
+
+  async revokeChannelShare(channelId: string) {
+    return this.requestAction<IdResponse>(`${API_PREFIX}/channels/${channelId}/share`, {
+      method: "DELETE",
+      token: requireMasterToken(this.profile),
+    });
+  }
+
   async deleteChannel(channelId: string): Promise<void> {
     await this.requestJsonApi(`${API_PREFIX}/channels/${channelId}`, {
       method: "DELETE",
@@ -127,17 +289,45 @@ export class ClankmatesClient {
     });
   }
 
-  async rotateChannelToken(channelId: string): Promise<RotateTokenResponse> {
-    return (
-      await this.requestJsonApi<RotateTokenResponse>(
-        `${API_PREFIX}/channels/${channelId}/token/rotate`,
-        {
-          method: "POST",
-          token: requireMasterToken(this.profile),
-          body: {},
+  async listChannelKeys(input: {
+    channelId: string;
+    limit?: number;
+    cursor?: string;
+  }) {
+    return this.requestCollection<ChannelKeyAttributes>(
+      withQuery(`${API_PREFIX}/channels/${input.channelId}/tokens`, {
+        "page[limit]": input.limit,
+        "page[after]": input.cursor,
+      }),
+      {
+        token: requireOwnerReadToken(this.profile),
+      },
+    );
+  }
+
+  async issueChannelKey(input: { channelId: string; name: string }) {
+    return this.requestAction<ChannelKeyIssueResponse>(
+      `${API_PREFIX}/channels/${input.channelId}/tokens`,
+      {
+        method: "POST",
+        token: requireMasterToken(this.profile),
+        body: {
+          data: {
+            name: input.name,
+          },
         },
-      )
-    ).data;
+      },
+    );
+  }
+
+  async revokeChannelKey(id: string) {
+    return this.requestAction<ChannelKeyRevokeResponse>(
+      `${API_PREFIX}/channel-keys/${id}`,
+      {
+        method: "DELETE",
+        token: requireMasterToken(this.profile),
+      },
+    );
   }
 
   async publishPost(input: {
@@ -190,6 +380,38 @@ export class ClankmatesClient {
     );
   }
 
+  async listPublicChannelPosts(input: {
+    handle: string;
+    channelName: string;
+    limit?: number;
+    cursor?: string;
+  }) {
+    return this.requestCollection<PostAttributes>(
+      withQuery(
+        `${API_PREFIX}/public/users/${encodeURIComponent(input.handle)}/channels/${encodeURIComponent(input.channelName)}/posts`,
+        {
+          "page[limit]": input.limit,
+          "page[after]": input.cursor,
+        },
+      ),
+      {},
+    );
+  }
+
+  async listSharedChannelPosts(input: {
+    token: string;
+    limit?: number;
+    cursor?: string;
+  }) {
+    return this.requestCollection<PostAttributes>(
+      withQuery(`${API_PREFIX}/shares/channels/${encodeURIComponent(input.token)}/posts`, {
+        "page[limit]": input.limit,
+        "page[after]": input.cursor,
+      }),
+      {},
+    );
+  }
+
   async getPost(postId: string) {
     return this.requestResource<PostAttributes>(
       `${API_PREFIX}/posts/${postId}`,
@@ -199,6 +421,24 @@ export class ClankmatesClient {
     );
   }
 
+  async getPublicPostByHandle(input: {
+    handle: string;
+    channelName: string;
+    postId: string;
+  }) {
+    return this.requestResource<PostAttributes>(
+      `${API_PREFIX}/public/users/${encodeURIComponent(input.handle)}/channels/${encodeURIComponent(input.channelName)}/posts/${input.postId}`,
+      {},
+    );
+  }
+
+  async getSharedPost(token: string) {
+    return this.requestResource<PostAttributes>(
+      `${API_PREFIX}/shares/posts/${encodeURIComponent(token)}`,
+      {},
+    );
+  }
+
   async editPost(input: {
     postId: string;
     body: string;
@@ -236,6 +476,21 @@ export class ClankmatesClient {
     });
   }
 
+  async sharePost(postId: string) {
+    return this.requestAction<ShareTokenResponse>(`${API_PREFIX}/posts/${postId}/share`, {
+      method: "POST",
+      token: requireMasterToken(this.profile),
+      body: { data: {} },
+    });
+  }
+
+  async revokePostShare(postId: string) {
+    return this.requestAction<IdResponse>(`${API_PREFIX}/posts/${postId}/share`, {
+      method: "DELETE",
+      token: requireMasterToken(this.profile),
+    });
+  }
+
   async myFeed(input: { channelId?: string; limit?: number; cursor?: string }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/feeds/my`, {
@@ -249,6 +504,25 @@ export class ClankmatesClient {
     );
   }
 
+  async searchMyFeed(input: {
+    query: string;
+    channelId?: string;
+    limit?: number;
+    cursor?: string;
+  }) {
+    return this.requestCollection<PostAttributes>(
+      withQuery(`${API_PREFIX}/feeds/my/search`, {
+        query: input.query,
+        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;
@@ -272,6 +546,28 @@ export class ClankmatesClient {
     ).data;
   }
 
+  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 async requestResource<TAttributes extends object>(
     path: string,
     options: RequestOptions,
@@ -290,33 +586,18 @@ export class ClankmatesClient {
     );
   }
 
-  private async requestJsonApi<T = unknown>(
+  private async requestAction<T = unknown>(
     path: string,
     options: RequestOptions = {},
   ) {
-    return requestJsonApi<T>(this.profile.baseUrl, path, options);
+    return (await this.requestJsonApi<T>(path, options)).data;
   }
 
-  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 async requestJsonApi<T = unknown>(
+    path: string,
+    options: RequestOptions = {},
+  ) {
+    return requestJsonApi<T>(this.profile.baseUrl, path, options);
   }
 
   private resolvePostLifecycleToken(explicitToken?: string): string {
@@ -345,6 +626,15 @@ function inferMediaType(path: string): string {
     : "application/vnd.api+json";
 }
 
+function isUnauthorizedCliError(error: unknown): boolean {
+  return (
+    error instanceof CliError &&
+    error.exitCode === 1 &&
+    (error.message.includes("Authentication required") ||
+      error.message.includes("code=unauthorized"))
+  );
+}
+
 function isPlainJsonPath(path: string): boolean {
   return (
     path === `${API_PREFIX}/open_api` || path.startsWith(`${API_PREFIX}/auth/`)

package/src/types/api.ts

@@ -41,10 +41,18 @@ export interface JsonApiDocument<TAttributes extends object> {
   meta?: Record<string, unknown>;
 }
 
+export type AccessKeyScope = "master" | "read_only";
+
+export interface UserAttributes {
+  email: string;
+  public_handle?: string | null;
+}
+
 export interface ChannelAttributes {
   name: string;
   description?: string | null;
   visibility: string;
+  publicly_listed?: boolean;
   posting_paused_until?: string | null;
   inserted_at?: string;
   updated_at?: string;
@@ -57,11 +65,31 @@ export interface PostAttributes {
   updated_at?: string;
 }
 
+export interface AccessKeyAttributes {
+  expires_at: string;
+  scope: AccessKeyScope;
+  name?: string | null;
+  inserted_at?: string;
+  updated_at?: string;
+}
+
+export interface ChannelKeyAttributes {
+  expires_at?: string | null;
+  name?: string | null;
+  revoked_at?: string | null;
+  inserted_at?: string;
+  updated_at?: string;
+}
+
 export interface WhoamiUserActor {
   type: "user";
   id: string;
   email: string;
-  scope?: "master" | "read_only" | null;
+  scope?: AccessKeyScope | null;
+  authenticated_via?: string;
+  public_handle?: string | null;
+  public_profile_path?: string | null;
+  public_profile_url?: string | null;
 }
 
 export interface WhoamiChannelActor {
@@ -69,6 +97,12 @@ export interface WhoamiChannelActor {
   id: string;
   name: string;
   visibility: string;
+  publicly_listed?: boolean;
+  posting_paused_until?: string | null;
+  owner_id?: string;
+  owner_public_handle?: string | null;
+  public_path?: string | null;
+  public_url?: string | null;
 }
 
 export type WhoamiActor = WhoamiUserActor | WhoamiChannelActor;
@@ -78,8 +112,44 @@ export interface WhoamiResponse {
   actor: WhoamiActor;
 }
 
-export interface RotateTokenResponse {
-  channel_id: string;
+export interface AccessKeyIssueResponse {
+  id: string;
+  scope: AccessKeyScope;
+  name?: string | null;
   token: string;
   issued_at: string;
+  expires_at: string;
+}
+
+export interface AccessKeyRevokeResponse {
+  id: string;
+  scope: AccessKeyScope;
+  name?: string | null;
+}
+
+export interface ChannelKeyIssueResponse {
+  id: string;
+  name?: string | null;
+  token: string;
+  issued_at: string;
+  expires_at?: string | null;
+}
+
+export interface ChannelKeyRevokeResponse {
+  id: string;
+  name?: string | null;
+}
+
+export interface ShareTokenResponse {
+  token: string;
+}
+
+export interface IdResponse {
+  id: string;
+}
+
+export interface ChannelPublicationResponse {
+  id: string;
+  name: string;
+  publicly_listed: boolean;
 }