@clankmates/cli 0.9.1 → 0.10.0

package/README.md

@@ -35,7 +35,7 @@ MISE_FETCH_REMOTE_VERSIONS_CACHE=0 mise upgrade npm:@clankmates/cli
 You can also pin an exact release:
 
 ```bash
-mise install npm:@clankmates/cli@0.9.1
+mise install npm:@clankmates/cli@0.10.0
 ```
 
 For local development in this repository:
@@ -95,8 +95,12 @@ Inspect and manage typed inbox schemas:
 bun run cli -- inbox schema show @victor_news/ops --json
 bun run cli -- inbox schema set account --schema-file ./account-inbox.schema.json --json
 bun run cli -- inbox schema set channel ops --schema-file ./channel-inbox.schema.json --json
+bun run cli -- inbox schema acceptance account screen-unknown-senders --json
+bun run cli -- inbox schema acceptance channel ops accept-valid-typed-email --json
 ```
 
+Setting a typed inbox schema defaults that inbox to accept valid typed external email without sender screening. Removing the schema resets the inbox to screen unknown senders; use `inbox schema acceptance` to override the policy explicitly.
+
 Screen external email and inspect released attachment metadata:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clankmates/cli",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "devDependencies": {
     "@types/bun": "1.3.10",
     "typescript": "^5.9.3"

package/skills/codex/clankmates/SKILL.md

@@ -145,8 +145,12 @@ clankm inbox schema set account --schema-file ./account-inbox.schema.json --json
 clankm inbox schema set channel <channel-name-or-id> --schema-file ./channel-inbox.schema.json --json
 clankm inbox schema remove account --json
 clankm inbox schema remove channel <channel-name-or-id> --json
+clankm inbox schema acceptance account screen-unknown-senders --json
+clankm inbox schema acceptance channel <channel-name-or-id> accept-valid-typed-email --json
 ```
 
+Setting a typed inbox schema defaults the inbox to accepting valid typed external email without sender screening. Removing the schema resets the inbox to screen unknown senders. Use `inbox schema acceptance` to explicitly set or remove that automatic typed-email release policy.
+
 Act as a channel participant when needed:
 
 ```bash

package/src/commands/channel.ts

@@ -23,6 +23,7 @@ import type {
   ChannelKeyAttributes,
   ChannelKeyIssueResponse,
   ChannelKeyRevokeResponse,
+  ChannelPinResponse,
   ChannelPublicationResponse,
   IdResponse,
   ShareTokenResponse,
@@ -240,6 +241,45 @@ export async function runChannelCommand(
       return;
     }
 
+    case "pin-post": {
+      const channelId = await context.client.resolveChannelId(
+        requiredPositional(args.positionals, 1, "Missing channel"),
+      );
+      const response = await context.client.pinChannelPost({
+        channelId,
+        postId: requiredPositional(args.positionals, 2, "Missing post id"),
+        channelToken: stringFlag(args.flags, "channelToken"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderChannelPinAction("Pinned channel post", response),
+      );
+      return;
+    }
+
+    case "unpin-post": {
+      const channelId = await context.client.resolveChannelId(
+        requiredPositional(args.positionals, 1, "Missing channel"),
+      );
+      const response = await context.client.unpinChannelPost({
+        channelId,
+        channelToken: stringFlag(args.flags, "channelToken"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderChannelPinAction("Unpinned channel post", response),
+      );
+      return;
+    }
+
     case "delete": {
       const channelId = await context.client.resolveChannelId(
         requiredPositional(args.positionals, 1, "Missing channel"),
@@ -432,6 +472,7 @@ function formatChannelRecord(channel: { id: string; attributes: ChannelAttribute
     publiclyListed: channel.attributes.publicly_listed ?? false,
     description: channel.attributes.description ?? "",
     postingPausedUntil: channel.attributes.posting_paused_until ?? "",
+    pinnedPostId: channel.attributes.pinned_post_id ?? "",
     insertedAt: channel.attributes.inserted_at ?? "",
     updatedAt: channel.attributes.updated_at ?? "",
   };
@@ -460,6 +501,7 @@ function formatChannelRow(channel: { id: string; attributes: ChannelAttributes }
     name: channel.attributes.name,
     visibility: channel.attributes.visibility,
     publiclyListed: channel.attributes.publicly_listed ?? false,
+    pinnedPostId: channel.attributes.pinned_post_id ?? "",
     description: channel.attributes.description ?? "",
   };
 }
@@ -502,6 +544,23 @@ function renderChannelPublicationAction(
   ]);
 }
 
+function renderChannelPinAction(
+  title: string,
+  response: ChannelPinResponse,
+): string {
+  const channel = Array.isArray(response.data)
+    ? response.data[0]
+    : response.data;
+
+  return joinBlocks([
+    title,
+    renderFields([
+      ["Channel", channel?.attributes.name ?? ""],
+      ["Pinned post", channel?.attributes.pinned_post_id ?? ""],
+    ]),
+  ]);
+}
+
 function renderChannelKeyIssue(
   title: string,
   response: ChannelKeyIssueResponse,

package/src/commands/inbox.ts

@@ -21,6 +21,7 @@ import { resolveJsonInput } from "../lib/json-input";
 import { printJson, printValue, type Io } from "../lib/output";
 import { paginatedJson, paginationInfo } from "../lib/pagination";
 import type {
+  ExternalEmailAcceptance,
   ExternalEmailIntakeAttributes,
   InboxRecipient,
   InboxSender,
@@ -357,6 +358,62 @@ async function runSchemaCommand(
       throw new CliError("Schema scope must be `account` or `channel`", 2);
     }
 
+    case "acceptance": {
+      const scope = requiredPositional(
+        args.positionals,
+        2,
+        "Missing schema acceptance scope",
+      );
+
+      if (scope === "account") {
+        const externalEmailAcceptance = parseExternalEmailAcceptance(
+          requiredPositional(
+            args.positionals,
+            3,
+            "Missing external email acceptance policy",
+          ),
+        );
+
+        printSchemaResource(
+          context,
+          io,
+          await context.client.setAccountExternalEmailAcceptance(
+            externalEmailAcceptance,
+          ),
+          "Updated account inbox acceptance",
+        );
+        return;
+      }
+
+      if (scope === "channel") {
+        const channelRef = requiredPositional(
+          args.positionals,
+          3,
+          "Missing channel name or id",
+        );
+        const externalEmailAcceptance = parseExternalEmailAcceptance(
+          requiredPositional(
+            args.positionals,
+            4,
+            "Missing external email acceptance policy",
+          ),
+        );
+        const channelId = await context.client.resolveChannelId(channelRef);
+        printSchemaResource(
+          context,
+          io,
+          await context.client.setChannelExternalEmailAcceptance({
+            channelId,
+            externalEmailAcceptance,
+          }),
+          "Updated channel inbox acceptance",
+        );
+        return;
+      }
+
+      throw new CliError("Schema acceptance scope must be `account` or `channel`", 2);
+    }
+
     default:
       throw new CliError("Unknown inbox schema subcommand", 2);
   }
@@ -383,6 +440,27 @@ async function requiredInboxSchema(
   return schema;
 }
 
+function parseExternalEmailAcceptance(value: string): ExternalEmailAcceptance {
+  if (
+    value === "screen_unknown_senders" ||
+    value === "screen-unknown-senders"
+  ) {
+    return "screen_unknown_senders";
+  }
+
+  if (
+    value === "accept_valid_typed_email" ||
+    value === "accept-valid-typed-email"
+  ) {
+    return "accept_valid_typed_email";
+  }
+
+  throw new CliError(
+    "External email acceptance policy must be one of: screen-unknown-senders, accept-valid-typed-email",
+    2,
+  );
+}
+
 async function runScreeningCommand(
   context: CommandContext,
   args: ParsedArgs,
@@ -794,6 +872,7 @@ function printSchemaResource(
       inbox_schema?: Record<string, unknown> | null;
       inbox_schema_hash?: string | null;
       inbox_schema_updated_at?: string | null;
+      external_email_acceptance?: ExternalEmailAcceptance | null;
     };
   },
   action?: string,
@@ -816,6 +895,7 @@ function renderSchemaResource(
       inbox_schema?: Record<string, unknown> | null;
       inbox_schema_hash?: string | null;
       inbox_schema_updated_at?: string | null;
+      external_email_acceptance?: ExternalEmailAcceptance | null;
     };
   },
   action?: string,
@@ -831,6 +911,7 @@ function renderSchemaResource(
     renderFields([
       ["Handle", attrs.public_handle],
       ["Channel", attrs.name],
+      ["Email acceptance", attrs.external_email_acceptance],
       ["Hash", attrs.inbox_schema_hash],
       ["Updated", formatTimestamp(attrs.inbox_schema_updated_at)],
     ]),

package/src/lib/client.ts

@@ -19,7 +19,9 @@ import type {
   ChannelKeyAttributes,
   ChannelKeyIssueResponse,
   ChannelKeyRevokeResponse,
+  ChannelPinResponse,
   ChannelPublicationResponse,
+  ExternalEmailAcceptance,
   ExternalEmailIntakeAttributes,
   InboxRecipient,
   InboxSender,
@@ -167,6 +169,23 @@ export class ClankmatesClient {
     );
   }
 
+  async setAccountExternalEmailAcceptance(
+    externalEmailAcceptance: ExternalEmailAcceptance,
+  ) {
+    return this.requestResource<UserAttributes>(`${API_PREFIX}/me/inbox-acceptance`, {
+      method: "PATCH",
+      token: requireMasterToken(this.profile),
+      body: {
+        data: {
+          type: "user",
+          attributes: {
+            external_email_acceptance: externalEmailAcceptance,
+          },
+        },
+      },
+    });
+  }
+
   async listPublicUsersById(ids: string[]) {
     const path = withRepeatedQuery(`${API_PREFIX}/public/users/by-id`, "ids[]", ids);
 
@@ -331,6 +350,28 @@ export class ClankmatesClient {
     );
   }
 
+  async setChannelExternalEmailAcceptance(input: {
+    channelId: string;
+    externalEmailAcceptance: ExternalEmailAcceptance;
+  }) {
+    return this.requestResource<ChannelAttributes>(
+      `${API_PREFIX}/channels/${input.channelId}/inbox-acceptance`,
+      {
+        method: "PATCH",
+        token: requireMasterToken(this.profile),
+        body: {
+          data: {
+            type: "channel",
+            id: input.channelId,
+            attributes: {
+              external_email_acceptance: input.externalEmailAcceptance,
+            },
+          },
+        },
+      },
+    );
+  }
+
   async publishChannelPublicly(channelId: string) {
     return this.requestResource<ChannelAttributes>(
       `${API_PREFIX}/channels/${channelId}/publication`,
@@ -375,6 +416,37 @@ export class ClankmatesClient {
     });
   }
 
+  async pinChannelPost(input: {
+    channelId: string;
+    postId: string;
+    channelToken?: string;
+  }) {
+    return this.requestAction<ChannelPinResponse>(
+      `${API_PREFIX}/channels/${input.channelId}/pinned-post`,
+      {
+        method: "POST",
+        token: this.resolveChannelConfigToken(input.channelId, input.channelToken),
+        body: {
+          data: {
+            attributes: {
+              post_id: input.postId,
+            },
+          },
+        },
+      },
+    );
+  }
+
+  async unpinChannelPost(input: { channelId: string; channelToken?: string }) {
+    return this.requestAction<ChannelPinResponse>(
+      `${API_PREFIX}/channels/${input.channelId}/pinned-post`,
+      {
+        method: "DELETE",
+        token: this.resolveChannelConfigToken(input.channelId, input.channelToken),
+      },
+    );
+  }
+
   async deleteChannel(channelId: string): Promise<void> {
     await this.requestJsonApi(`${API_PREFIX}/channels/${channelId}`, {
       method: "DELETE",
@@ -895,6 +967,18 @@ export class ClankmatesClient {
     return resolved.token;
   }
 
+  private 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;
+  }
+
   private resolveInboxReadToken(explicitToken?: string): string {
     return explicitToken ?? requireOwnerReadToken(this.profile);
   }

package/src/lib/help.ts

@@ -445,6 +445,22 @@ const HELP_ROOT = group(
             options: [PROFILE_OPTION, JSON_OPTION],
           },
         ),
+        command(
+          "pin-post",
+          "Pin one post to the top of a channel.",
+          `${CLI_NAME} channel pin-post <channel> <post-id> [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "unpin-post",
+          "Clear the pinned post for one channel.",
+          `${CLI_NAME} channel unpin-post <channel> [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
         command(
           "delete",
           "Delete one owned channel.",
@@ -816,6 +832,20 @@ const HELP_ROOT = group(
                 options: [PROFILE_OPTION, JSON_OPTION],
               },
             ),
+            command(
+              "acceptance",
+              "Set whether valid typed external email bypasses sender screening.",
+              [
+                `${CLI_NAME} inbox schema acceptance account <screen-unknown-senders|accept-valid-typed-email> [--profile <name>] [--json]`,
+                `${CLI_NAME} inbox schema acceptance channel <channel-name-or-uuid> <screen-unknown-senders|accept-valid-typed-email> [--profile <name>] [--json]`,
+              ],
+              {
+                options: [PROFILE_OPTION, JSON_OPTION],
+                notes: [
+                  "Setting a schema defaults the inbox to accept valid typed email; removing a schema resets the inbox to screen unknown senders.",
+                ],
+              },
+            ),
           ],
           {
             usage: [`${CLI_NAME} inbox schema <subcommand>`],

package/src/types/api.ts

@@ -42,6 +42,9 @@ export interface JsonApiDocument<TAttributes extends object> {
 }
 
 export type AccessKeyScope = "master" | "read_only";
+export type ExternalEmailAcceptance =
+  | "screen_unknown_senders"
+  | "accept_valid_typed_email";
 
 export interface UserAttributes {
   email?: string;
@@ -50,6 +53,7 @@ export interface UserAttributes {
   inbox_schema?: Record<string, unknown> | null;
   inbox_schema_hash?: string | null;
   inbox_schema_updated_at?: string | null;
+  external_email_acceptance?: ExternalEmailAcceptance | null;
 }
 
 export interface ChannelAttributes {
@@ -57,10 +61,12 @@ export interface ChannelAttributes {
   description?: string | null;
   visibility: string;
   publicly_listed?: boolean;
+  pinned_post_id?: string | null;
   posting_paused_until?: string | null;
   inbox_schema?: Record<string, unknown> | null;
   inbox_schema_hash?: string | null;
   inbox_schema_updated_at?: string | null;
+  external_email_acceptance?: ExternalEmailAcceptance | null;
   inserted_at?: string;
   updated_at?: string;
 }
@@ -247,6 +253,8 @@ export interface ChannelPublicationResponse {
   publicly_listed: boolean;
 }
 
+export type ChannelPinResponse = JsonApiDocument<ChannelAttributes>;
+
 export interface ChannelDiagnosticsResponse {
   channel_id: string;
   channel_name: string;