@clankid/cli 0.17.0

package/src/lib/cache/store.ts

@@ -0,0 +1,195 @@
+import { Database } from "bun:sqlite";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+import { getCachePath } from "../paths";
+import { CLI_VERSION } from "../version";
+import type { CacheScope, SyncScopeRow } from "./types";
+
+const MIGRATION_VERSION = 1;
+
+export class SyncCache {
+  private readonly db: Database;
+
+  constructor(private readonly dbPath = getCachePath()) {
+    this.db = new Database(dbPath, { create: true });
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec("PRAGMA foreign_keys = ON");
+    this.migrate();
+  }
+
+  path(): string {
+    return this.dbPath;
+  }
+
+  get(scopeKey: string): SyncScopeRow | undefined {
+    return this.db
+      .query<SyncScopeRow, [string]>(
+        `select scope_key, base_url, profile, actor_key, resource, params_json,
+                server_timestamp, cached_at, cli_version
+           from sync_scopes
+          where scope_key = ?`,
+      )
+      .get(scopeKey) ?? undefined;
+  }
+
+  list(input: { baseUrl?: string; profile?: string } = {}): SyncScopeRow[] {
+    if (input.baseUrl && input.profile) {
+      return this.db
+        .query<SyncScopeRow, [string, string]>(
+          `select scope_key, base_url, profile, actor_key, resource, params_json,
+                  server_timestamp, cached_at, cli_version
+             from sync_scopes
+            where base_url = ? and profile = ?
+            order by resource, scope_key`,
+        )
+        .all(input.baseUrl, input.profile);
+    }
+
+    return this.db
+      .query<SyncScopeRow, []>(
+        `select scope_key, base_url, profile, actor_key, resource, params_json,
+                server_timestamp, cached_at, cli_version
+           from sync_scopes
+          order by base_url, profile, resource, scope_key`,
+      )
+      .all();
+  }
+
+  upsert(input: {
+    scope: CacheScope;
+    baseUrl: string;
+    profile: string;
+    serverTimestamp: string;
+  }): void {
+    this.db
+      .query<
+        unknown,
+        [string, string, string, string, string, string, string, string, string]
+      >(
+        `insert into sync_scopes (
+           scope_key, base_url, profile, actor_key, resource, params_json,
+           server_timestamp, cached_at, cli_version
+         )
+         values (?, ?, ?, ?, ?, ?, ?, ?, ?)
+         on conflict(scope_key) do update set
+           base_url = excluded.base_url,
+           profile = excluded.profile,
+           actor_key = excluded.actor_key,
+           resource = excluded.resource,
+           params_json = excluded.params_json,
+           server_timestamp = excluded.server_timestamp,
+           cached_at = excluded.cached_at,
+           cli_version = excluded.cli_version`,
+      )
+      .run(
+        input.scope.scopeKey,
+        input.baseUrl,
+        input.profile,
+        input.scope.actorKey,
+        input.scope.resource,
+        stableJson(input.scope.params),
+        input.serverTimestamp,
+        new Date().toISOString(),
+        CLI_VERSION,
+      );
+  }
+
+  clear(input: { scopeKey?: string; baseUrl?: string; profile?: string } = {}): number {
+    if (input.scopeKey) {
+      const result = this.db
+        .query<unknown, [string]>("delete from sync_scopes where scope_key = ?")
+        .run(input.scopeKey);
+      return result.changes;
+    }
+
+    if (input.baseUrl && input.profile) {
+      const result = this.db
+        .query<unknown, [string, string]>(
+          "delete from sync_scopes where base_url = ? and profile = ?",
+        )
+        .run(input.baseUrl, input.profile);
+      return result.changes;
+    }
+
+    const result = this.db.query<unknown, []>("delete from sync_scopes").run();
+    return result.changes;
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  private migrate(): void {
+    this.db.exec(`
+      create table if not exists schema_migrations (
+        version integer primary key,
+        applied_at text not null
+      );
+    `);
+
+    const applied = this.db
+      .query<{ version: number }, [number]>(
+        "select version from schema_migrations where version = ?",
+      )
+      .get(MIGRATION_VERSION);
+
+    if (applied) {
+      return;
+    }
+
+    this.db.exec(`
+      create table if not exists sync_scopes (
+        scope_key text primary key,
+        base_url text not null,
+        profile text not null,
+        actor_key text not null,
+        resource text not null,
+        params_json text not null,
+        server_timestamp text,
+        cached_at text not null,
+        cli_version text not null
+      );
+
+      create index if not exists sync_scopes_profile_idx
+        on sync_scopes(base_url, profile);
+    `);
+
+    this.db
+      .query<unknown, [number, string]>(
+        "insert into schema_migrations(version, applied_at) values (?, ?)",
+      )
+      .run(MIGRATION_VERSION, new Date().toISOString());
+  }
+}
+
+export async function ensureCacheParentDirectory(
+  cachePath = getCachePath(),
+): Promise<void> {
+  await mkdir(path.dirname(cachePath), { recursive: true });
+}
+
+export async function openSyncCache(cachePath = getCachePath()): Promise<SyncCache> {
+  await ensureCacheParentDirectory(cachePath);
+  return new SyncCache(cachePath);
+}
+
+function stableJson(value: Record<string, unknown>): string {
+  return JSON.stringify(sortObject(value));
+}
+
+function sortObject(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(sortObject);
+  }
+
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, sortObject(entry)]),
+  );
+}

package/src/lib/cache/types.ts

@@ -0,0 +1,31 @@
+export interface SyncScopeRow {
+  scope_key: string;
+  base_url: string;
+  profile: string;
+  actor_key: string;
+  resource: string;
+  params_json: string;
+  server_timestamp?: string | null;
+  cached_at: string;
+  cli_version: string;
+}
+
+export interface CacheScope {
+  scopeKey: string;
+  resource: string;
+  params: Record<string, unknown>;
+  actorKey: string;
+}
+
+export interface CachePlan {
+  scope: CacheScope;
+  previousServerTimestamp?: string;
+  hit: boolean;
+}
+
+export interface CacheResult {
+  scopeKey: string;
+  hit: boolean;
+  previousServerTimestamp?: string;
+  savedServerTimestamp?: string;
+}

package/src/lib/cache.ts

@@ -0,0 +1,135 @@
+import { booleanFlag, stringFlag, type ParsedArgs } from "./args";
+import type { CommandContext } from "./context";
+import { CliError } from "./errors";
+import { actorKey } from "./cache/scopes";
+import { openSyncCache } from "./cache/store";
+import type { CachePlan, CacheResult, CacheScope } from "./cache/types";
+
+export type { CachePlan, CacheResult, CacheScope, SyncScopeRow } from "./cache/types";
+export { SyncCache, ensureCacheParentDirectory, openSyncCache } from "./cache/store";
+export {
+  feedMyScope,
+  feedSearchScope,
+  hashValue,
+  inboxMessagesScope,
+  inboxThreadsScope,
+  ownedPostsScope,
+  publicActorKey,
+  publicPostsScope,
+  sharedActorKey,
+  sharedPostsScope,
+} from "./cache/scopes";
+
+export function cacheFlags(args: ParsedArgs): {
+  sinceCache: boolean;
+  saveCache: boolean;
+} {
+  return {
+    sinceCache: booleanFlag(args.flags, "sinceCache"),
+    saveCache: booleanFlag(args.flags, "saveCache"),
+  };
+}
+
+export function assertSinceFlags(args: ParsedArgs): void {
+  if (stringFlag(args.flags, "since") && booleanFlag(args.flags, "sinceCache")) {
+    throw new CliError("Use only one of `--since` or `--since-cache`", 2);
+  }
+}
+
+export async function prepareCachePlan(
+  context: CommandContext,
+  scope: CacheScope,
+): Promise<CachePlan> {
+  const cache = await openSyncCache();
+
+  try {
+    const row = cache.get(scope.scopeKey);
+    return {
+      scope,
+      previousServerTimestamp: row?.server_timestamp ?? undefined,
+      hit: Boolean(row?.server_timestamp),
+    };
+  } finally {
+    cache.close();
+  }
+}
+
+export async function saveCacheTimestamp(
+  context: CommandContext,
+  scope: CacheScope,
+  meta: Record<string, unknown> | undefined,
+): Promise<string | undefined> {
+  const serverTimestamp = extractServerTimestamp(meta);
+
+  if (!serverTimestamp) {
+    return undefined;
+  }
+
+  const cache = await openSyncCache();
+
+  try {
+    cache.upsert({
+      scope,
+      baseUrl: context.profile.baseUrl,
+      profile: context.profileName,
+      serverTimestamp,
+    });
+  } finally {
+    cache.close();
+  }
+
+  return serverTimestamp;
+}
+
+export function cacheResult(
+  plan: CachePlan | undefined,
+  savedServerTimestamp?: string,
+): CacheResult | undefined {
+  if (!plan && !savedServerTimestamp) {
+    return undefined;
+  }
+
+  return {
+    scopeKey: plan?.scope.scopeKey ?? "",
+    hit: plan?.hit ?? false,
+    previousServerTimestamp: plan?.previousServerTimestamp,
+    savedServerTimestamp,
+  };
+}
+
+export function extractServerTimestamp(
+  meta: Record<string, unknown> | undefined,
+): string | undefined {
+  if (!meta) {
+    return undefined;
+  }
+
+  for (const key of [
+    "server_time",
+    "server_timestamp",
+    "serverTimestamp",
+    "latest_server_timestamp",
+    "latestServerTimestamp",
+  ]) {
+    const value = meta[key];
+
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+export function changeResponseMeta(response: {
+  server_time?: string;
+}): Record<string, unknown> {
+  return response.server_time ? { server_time: response.server_time } : {};
+}
+
+export async function authenticatedActorKey(
+  context: CommandContext,
+  identityKey?: string,
+): Promise<string> {
+  return actorKey((await context.client.whoami(identityKey)).actor);
+}

package/src/lib/client/auth.ts

@@ -0,0 +1,163 @@
+import { requestJson } from "../http";
+import { CliError } from "../errors";
+import {
+  requireMasterToken,
+  requireOwnerReadToken,
+} from "../tokens";
+import type {
+  AccountBootstrapCompleteResponse,
+  AccountBootstrapRequestResponse,
+  AccessKeyAttributes,
+  AccessKeyIssueResponse,
+  AccessKeyRevokeResponse,
+  AccessKeyScope,
+  WhoamiResponse,
+} from "../../types/api";
+import { API_PREFIX, type ApiClientCore } from "./core";
+
+export async function canAuthenticate(
+  core: ApiClientCore,
+  token: string,
+): Promise<boolean> {
+  try {
+    await whoami(core, token);
+    return true;
+  } catch (error) {
+    if (isUnauthorizedCliError(error)) {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+export async function validateMasterToken(
+  core: ApiClientCore,
+  token: string,
+): Promise<void> {
+  const response = await whoami(core, token);
+
+  if (
+    response.actor.type !== "user" ||
+    response.actor.scope === "read_only"
+  ) {
+    throw new CliError("Provided token is not a master token.");
+  }
+}
+
+export async function validateReadOnlyToken(
+  core: ApiClientCore,
+  token: string,
+): Promise<void> {
+  const response = await whoami(core, token);
+
+  if (
+    response.actor.type !== "user" ||
+    response.actor.scope !== "read_only"
+  ) {
+    throw new CliError("Provided token is not a read-only token.");
+  }
+}
+
+export async function whoami(
+  core: ApiClientCore,
+  token = requireOwnerReadToken(core.profile),
+): Promise<WhoamiResponse> {
+  return (
+    await requestJson<WhoamiResponse>(
+      core.profile.baseUrl,
+      `${API_PREFIX}/auth/whoami`,
+      { token },
+    )
+  ).data;
+}
+
+export async function requestAccountBootstrap(
+  core: ApiClientCore,
+  input: { email: string; publicHandle: string },
+): Promise<AccountBootstrapRequestResponse> {
+  return (
+    await requestJson<AccountBootstrapRequestResponse>(
+      core.profile.baseUrl,
+      `${API_PREFIX}/auth/bootstrap/request`,
+      {
+        method: "POST",
+        body: {
+          email: input.email,
+          public_handle: input.publicHandle,
+        },
+      },
+    )
+  ).data;
+}
+
+export async function completeAccountBootstrap(
+  core: ApiClientCore,
+  input: { bootstrapId: string; code: string; keyName?: string },
+): Promise<AccountBootstrapCompleteResponse> {
+  return (
+    await requestJson<AccountBootstrapCompleteResponse>(
+      core.profile.baseUrl,
+      `${API_PREFIX}/auth/bootstrap/complete`,
+      {
+        method: "POST",
+        body: {
+          bootstrap_id: input.bootstrapId,
+          code: input.code,
+          key_name: input.keyName,
+        },
+      },
+    )
+  ).data;
+}
+
+export async function listAccessKeys(
+  core: ApiClientCore,
+  scope?: AccessKeyScope,
+) {
+  const path = scope
+    ? `${API_PREFIX}/me/access-keys/scopes/${encodeURIComponent(scope)}`
+    : `${API_PREFIX}/me/access-keys`;
+
+  return core.requestCollection<AccessKeyAttributes>(path, {
+    token: requireOwnerReadToken(core.profile),
+  });
+}
+
+export async function issueAccessKey(
+  core: ApiClientCore,
+  input: { scope: AccessKeyScope; name: string },
+) {
+  return core.requestAction<AccessKeyIssueResponse>(
+    `${API_PREFIX}/me/access-keys`,
+    {
+      method: "POST",
+      token: requireMasterToken(core.profile),
+      body: {
+        data: {
+          scope: input.scope,
+          name: input.name,
+        },
+      },
+    },
+  );
+}
+
+export async function revokeAccessKey(core: ApiClientCore, id: string) {
+  return core.requestAction<AccessKeyRevokeResponse>(
+    `${API_PREFIX}/me/access-keys/${id}`,
+    {
+      method: "DELETE",
+      token: requireMasterToken(core.profile),
+    },
+  );
+}
+
+function isUnauthorizedCliError(error: unknown): boolean {
+  return (
+    error instanceof CliError &&
+    error.exitCode === 1 &&
+    (error.message.includes("Authentication required") ||
+      error.message.includes("code=unauthorized"))
+  );
+}

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,
+  resolveIdentityActorOrMasterToken,
+  resolveIdentityCredential,
+} 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 = resolveIdentityActorOrMasterToken(
+      this.profile,
+      explicitToken,
+    );
+
+    if (!resolved.token) {
+      throw new CliError(
+        "No identity credential available for post edit/delete. Provide --identity-key, set CLANKID_IDENTITY_KEY, configure a single saved identity key, or configure a master token.",
+      );
+    }
+
+    return resolved.token;
+  }
+
+  resolveIdentityConfigKey(identityId: string, explicitToken?: string): string {
+    const resolved = resolveIdentityCredential(this.profile, identityId, explicitToken);
+
+    if (!resolved.token) {
+      throw new CliError(
+        "No identity credential available for identity configuration. Provide --identity-key, save an identity key for this identity, 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;
+}