@clankid/cli 0.17.0

package/src/lib/tokens.ts

@@ -0,0 +1,284 @@
+import { readFileSync } from "node:fs";
+
+import { CliError } from "./errors";
+import type { ProfileConfig } from "../types/api";
+
+interface ResolvedToken {
+  token?: string;
+  source: "flag" | "env" | "config" | "none";
+}
+
+export function resolveReadOnlyToken(profile: ProfileConfig): ResolvedToken {
+  const envToken = process.env.CLANKID_READ_ONLY_TOKEN;
+
+  if (envToken) {
+    return {
+      token: envToken,
+      source: "env"
+    };
+  }
+
+  if (profile.readOnlyToken) {
+    return {
+      token: profile.readOnlyToken,
+      source: "config"
+    };
+  }
+
+  return {
+    source: "none"
+  };
+}
+
+export function resolveMasterToken(profile: ProfileConfig): ResolvedToken {
+  const envToken = process.env.CLANKID_MASTER_TOKEN;
+
+  if (envToken) {
+    return {
+      token: envToken,
+      source: "env"
+    };
+  }
+
+  if (profile.masterToken) {
+    return {
+      token: profile.masterToken,
+      source: "config"
+    };
+  }
+
+  return {
+    source: "none"
+  };
+}
+
+export function resolveOwnerReadToken(profile: ProfileConfig): ResolvedToken {
+  const readOnlyToken = resolveReadOnlyToken(profile);
+
+  if (readOnlyToken.token) {
+    return readOnlyToken;
+  }
+
+  return resolveMasterToken(profile);
+}
+
+export function resolveIdentityKey(
+  profile: ProfileConfig,
+  identityId: string,
+  explicitToken?: string
+): ResolvedToken {
+  if (explicitToken) {
+    return {
+      token: explicitToken,
+      source: "flag"
+    };
+  }
+
+  const envToken = process.env.CLANKID_IDENTITY_KEY;
+
+  if (envToken) {
+    return {
+      token: envToken,
+      source: "env"
+    };
+  }
+
+  const envMap = loadEnvIdentityKeyMap();
+  const mappedToken = envMap[identityId];
+
+  if (mappedToken) {
+    return {
+      token: mappedToken,
+      source: "env"
+    };
+  }
+
+  const storedToken = profile.identityKeys[identityId]?.token;
+
+  if (storedToken) {
+    return {
+      token: storedToken,
+      source: "config"
+    };
+  }
+
+  return {
+    source: "none"
+  };
+}
+
+export function resolveIdentityCredential(
+  profile: ProfileConfig,
+  identityId: string,
+  explicitToken?: string
+): ResolvedToken {
+  const identityKey = resolveIdentityKey(profile, identityId, explicitToken);
+
+  if (identityKey.token) {
+    return identityKey;
+  }
+
+  return resolveMasterToken(profile);
+}
+
+export function resolveIdentityActorOrMasterToken(
+  profile: ProfileConfig,
+  explicitToken?: string
+): ResolvedToken {
+  const identityKey = resolveSingleIdentityActorToken(profile, explicitToken);
+
+  if (identityKey.token) {
+    return identityKey;
+  }
+
+  return resolveMasterToken(profile);
+}
+
+export function requireMasterToken(profile: ProfileConfig): string {
+  const resolved = resolveMasterToken(profile);
+
+  if (!resolved.token) {
+    throw new CliError("No master token configured. Set `CLANKID_MASTER_TOKEN` or run `clank auth login --master-token <token>`.");
+  }
+
+  return resolved.token;
+}
+
+export function requireOwnerReadToken(profile: ProfileConfig): string {
+  const resolved = resolveOwnerReadToken(profile);
+
+  if (!resolved.token) {
+    throw new CliError(
+      "No owner read token configured. Set `CLANKID_READ_ONLY_TOKEN`, `CLANKID_MASTER_TOKEN`, or run `clank auth login --read-only-token <token>` / `clank auth login --master-token <token>`."
+    );
+  }
+
+  return resolved.token;
+}
+
+function loadEnvIdentityKeyMap(): Record<string, string> {
+  const inline = process.env.CLANKID_IDENTITY_KEYS_JSON;
+
+  if (inline) {
+    return parseIdentityKeyMap(inline, "CLANKID_IDENTITY_KEYS_JSON");
+  }
+
+  const filePath = process.env.CLANKID_IDENTITY_KEYS_FILE;
+
+  if (!filePath) {
+    return {};
+  }
+
+  let raw: string;
+
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch (error) {
+    throw new CliError(
+      `Failed to read identity key file from ${filePath}: ${(error as Error).message}`
+    );
+  }
+
+  return parseIdentityKeyMap(raw, "CLANKID_IDENTITY_KEYS_FILE");
+}
+
+function resolveSingleIdentityActorToken(
+  profile: ProfileConfig,
+  explicitToken?: string
+): ResolvedToken {
+  if (explicitToken) {
+    return {
+      token: explicitToken,
+      source: "flag"
+    };
+  }
+
+  const envToken = process.env.CLANKID_IDENTITY_KEY;
+
+  if (envToken) {
+    return {
+      token: envToken,
+      source: "env"
+    };
+  }
+
+  const envMapToken = resolveSingleMappedToken(loadEnvIdentityKeyMap());
+
+  if (envMapToken) {
+    return {
+      token: envMapToken,
+      source: "env"
+    };
+  }
+
+  const storedToken = resolveSingleStoredToken(profile);
+
+  if (storedToken) {
+    return {
+      token: storedToken,
+      source: "config"
+    };
+  }
+
+  return {
+    source: "none"
+  };
+}
+
+function resolveSingleMappedToken(tokenMap: Record<string, string>): string | undefined {
+  const uniqueTokens = [...new Set(Object.values(tokenMap).filter((value) => value.length > 0))];
+
+  if (uniqueTokens.length !== 1) {
+    return undefined;
+  }
+
+  return uniqueTokens[0];
+}
+
+function resolveSingleStoredToken(profile: ProfileConfig): string | undefined {
+  const uniqueTokens = [
+    ...new Set(
+      Object.values(profile.identityKeys)
+        .map((value) => value.token)
+        .filter((value): value is string => typeof value === "string" && value.length > 0)
+    )
+  ];
+
+  if (uniqueTokens.length !== 1) {
+    return undefined;
+  }
+
+  return uniqueTokens[0];
+}
+
+function parseIdentityKeyMap(raw: string, source: string): Record<string, string> {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new CliError(`Failed to parse ${source} as JSON: ${(error as Error).message}`);
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CliError(`${source} must be a JSON object keyed by identity id.`);
+  }
+
+  const tokenMap: Record<string, string> = {};
+
+  for (const [identityId, value] of Object.entries(parsed as Record<string, unknown>)) {
+    if (typeof value === "string") {
+      tokenMap[identityId] = value;
+      continue;
+    }
+
+    if (value && typeof value === "object" && typeof (value as { token?: unknown }).token === "string") {
+      tokenMap[identityId] = (value as { token: string }).token;
+      continue;
+    }
+
+    throw new CliError(`${source} entry for identity ${identityId} must be a string or { "token": string }.`);
+  }
+
+  return tokenMap;
+}

package/src/lib/version.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+function loadCliVersion(): string {
+  try {
+    const packageJsonPath = fileURLToPath(
+      new URL("../../package.json", import.meta.url),
+    );
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+      version?: string;
+    };
+
+    return packageJson.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+export const CLI_VERSION = loadCliVersion();

package/src/types/.gitkeep

@@ -0,0 +1 @@
+

package/src/types/api.ts

@@ -0,0 +1,320 @@
+export type OutputMode = "json" | "table";
+
+export type ProfileName = string;
+
+export interface StoredIdentityKey {
+  token: string;
+  updatedAt: string;
+}
+
+export interface ProfileConfig {
+  baseUrl: string;
+  output: OutputMode;
+  masterToken?: string;
+  readOnlyToken?: string;
+  identityKeys: Record<string, StoredIdentityKey>;
+}
+
+export interface ConfigFile {
+  version: 2;
+  activeProfile: ProfileName;
+  profiles: Record<ProfileName, ProfileConfig>;
+}
+
+export interface JsonApiResource<TAttributes extends object> {
+  id: string;
+  type: string;
+  attributes: TAttributes;
+}
+
+export interface JsonApiError {
+  code?: string;
+  title?: string;
+  detail?: string;
+  source?: Record<string, unknown>;
+}
+
+export interface JsonApiDocument<TAttributes extends object> {
+  data: JsonApiResource<TAttributes> | JsonApiResource<TAttributes>[];
+  errors?: JsonApiError[];
+  links?: Record<string, string | null>;
+  meta?: Record<string, unknown>;
+}
+
+export type AccessKeyScope = "master" | "read_only";
+export type ExternalEmailAcceptance =
+  | "screen_unknown_senders"
+  | "accept_valid_typed_email";
+
+export interface UserAttributes {
+  email?: string;
+  public_profile_id?: string;
+  public_handle?: string | null;
+  inbox_schema?: Record<string, unknown> | null;
+  inbox_schema_hash?: string | null;
+  inbox_schema_updated_at?: string | null;
+  external_email_acceptance?: ExternalEmailAcceptance | null;
+}
+
+export interface IdentityAttributes {
+  name: string;
+  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;
+}
+
+export interface PostAttributes {
+  body?: string | null;
+  content_format?: ContentFormat;
+  payload?: Record<string, unknown> | null;
+  source: string;
+  identity_id?: string;
+  identity_name?: string;
+  inserted_at?: string;
+  updated_at?: string;
+}
+
+export type ContentFormat = "markdown" | "json";
+export type ContentFilter = ContentFormat | "all";
+export type PayloadOp = "exists" | "eq";
+
+export interface StructuredContentInput {
+  body?: string;
+  payload?: Record<string, unknown>;
+  contentFormat?: ContentFormat;
+}
+
+export interface PayloadFilters {
+  contentFormat?: ContentFilter;
+  payloadContains?: string;
+  payloadPath?: string;
+  payloadOp?: PayloadOp;
+  payloadValue?: string;
+}
+
+export type MailboxType = "account" | "identity";
+export type ThreadStatus = "pending" | "open" | "blocked";
+export type ThreadStatusFilter = ThreadStatus | "all";
+export type MailboxFilter = MailboxType | "all";
+export type ParticipantScope = "account" | "owner";
+export type LatestFirstOrder = "latest" | "oldest";
+
+export interface ChangeCheckResponse {
+  has_updates: boolean;
+  server_time?: string;
+  recommended_poll_after_ms?: number;
+}
+
+export type InboxRecipient =
+  | { type: "user"; address: { kind: "handle"; value: string } }
+  | { type: "user"; address: { kind: "id"; value: string } }
+  | { type: "identity"; address: { kind: "id"; value: string } }
+  | {
+      type: "identity";
+      address: {
+        kind: "owner_handle_and_identity_name";
+        owner_handle: string;
+        identity_name: string;
+      };
+    };
+
+export interface InboxSender {
+  type: "identity";
+  address: {
+    kind: "id";
+    value: string;
+  };
+}
+
+export interface ThreadAttributes {
+  mailbox_type: MailboxType;
+  status: ThreadStatus;
+  participant_a_owner_id?: string | null;
+  participant_a_identity_id?: string | null;
+  participant_b_owner_id?: string | null;
+  participant_b_identity_id?: string | null;
+  opened_at?: string | null;
+  expires_at?: string | null;
+  last_message_at?: string;
+  participant_a_seen_at?: string | null;
+  participant_a_archived_at?: string | null;
+  participant_a_blocked_at?: string | null;
+  participant_a_resolved_at?: string | null;
+  participant_b_seen_at?: string | null;
+  participant_b_archived_at?: string | null;
+  participant_b_blocked_at?: string | null;
+  participant_b_resolved_at?: string | null;
+  inserted_at?: string;
+  updated_at?: string;
+}
+
+export interface MessageAttributes {
+  body?: string | null;
+  content_format?: ContentFormat;
+  payload?: Record<string, unknown> | null;
+  sender_owner_id?: string | null;
+  sender_identity_id?: string | null;
+  external_email_sender_id?: string | null;
+  thread_id?: string | null;
+  context_post_id?: string | null;
+  inserted_at?: string;
+}
+
+export interface ExternalEmailIntakeAttributes {
+  postmark_message_id?: string | null;
+  raw_recipient?: string | null;
+  subject?: string | null;
+  body?: string | null;
+  attachment_count?: number | null;
+  attachment_metadata?: Array<Record<string, unknown>> | null;
+  attachments_withheld?: boolean | null;
+  status?: string | null;
+  decision?: string | null;
+  received_count?: number | null;
+  last_received_at?: string | null;
+  released_at?: string | null;
+  owner_id?: string | null;
+  target_identity_id?: string | null;
+  external_email_sender_id?: string | null;
+  released_thread_id?: string | null;
+}
+
+export interface MessageAttachmentAttributes {
+  name?: string | null;
+  content_type?: string | null;
+  content_length?: number | null;
+  message_id?: string | null;
+  inserted_at?: string;
+}
+
+export interface AccessKeyAttributes {
+  expires_at: string;
+  scope: AccessKeyScope;
+  name?: string | null;
+  inserted_at?: string;
+  updated_at?: string;
+}
+
+export interface IdentityKeyAttributes {
+  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?: AccessKeyScope | null;
+  authenticated_via?: string;
+  public_handle?: string | null;
+  public_profile_path?: string | null;
+  public_profile_url?: string | null;
+}
+
+export interface WhoamiIdentityActor {
+  type: "identity";
+  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 | WhoamiIdentityActor;
+
+export interface WhoamiResponse {
+  authenticated: true;
+  actor: WhoamiActor;
+}
+
+export interface AccountBootstrapRequestResponse {
+  bootstrap_id: string;
+  expires_at: string;
+  code_length: number;
+}
+
+export interface AccountBootstrapCompleteResponse {
+  user: {
+    id?: string;
+    email?: string;
+    public_handle?: string | null;
+    public_path?: string | null;
+    public_url?: string | null;
+  };
+  access_key: AccessKeyIssueResponse;
+}
+
+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 IdentityKeyIssueResponse {
+  id: string;
+  name?: string | null;
+  token: string;
+  issued_at: string;
+  expires_at?: string | null;
+}
+
+export interface IdentityKeyRevokeResponse {
+  id: string;
+  name?: string | null;
+}
+
+export interface ShareTokenResponse {
+  token: string;
+}
+
+export interface IdResponse {
+  id: string;
+}
+
+export interface IdentityPublicationResponse {
+  id: string;
+  name: string;
+  publicly_listed: boolean;
+}
+
+export type IdentityPinResponse = JsonApiDocument<IdentityAttributes>;
+
+export interface IdentityDiagnosticsResponse {
+  identity_id: string;
+  identity_name: string;
+  identity_description?: string | null;
+  active_identity_key_count: number;
+  last_posted_at?: string | null;
+  posting_paused_until?: string | null;
+  latest_blocked_write_at?: string | null;
+  latest_blocked_write_reason?: string | null;
+  latest_blocked_write_reason_label?: string | null;
+  recent_post_window_days: number;
+  recent_block_window_hours: number;
+  state_codes: string[];
+  state_labels: string[];
+}

package/src/types/placeholder.d.ts

@@ -0,0 +1 @@
+export {};