@clankmates/cli 0.11.0 → 0.12.0

package/src/lib/cache.ts

@@ -0,0 +1,553 @@
+import { Database } from "bun:sqlite";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+import { booleanFlag, stringFlag, type ParsedArgs } from "./args";
+import type { CommandContext } from "./context";
+import { CliError } from "./errors";
+import { getCachePath } from "./paths";
+import { CLI_VERSION } from "./version";
+import type { WhoamiActor } from "../types/api";
+
+const MIGRATION_VERSION = 1;
+const PUBLIC_ACTOR_KEY = "public";
+const SHARED_ACTOR_KEY = "shared";
+
+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;
+}
+
+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);
+}
+
+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,
+  channelToken?: string,
+): Promise<string> {
+  return actorKey((await context.client.whoami(channelToken)).actor);
+}
+
+export function publicActorKey(): string {
+  return PUBLIC_ACTOR_KEY;
+}
+
+export function sharedActorKey(): string {
+  return SHARED_ACTOR_KEY;
+}
+
+export function feedMyScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  channelId?: string;
+  before?: string;
+}): CacheScope {
+  const channel = input.channelId ?? "all";
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "feed:my",
+    parts: ["feed", "my", channel, before],
+    params: { channel, before },
+  });
+}
+
+export function feedSearchScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  query: string;
+  channelId?: string;
+  before?: string;
+}): CacheScope {
+  const channel = input.channelId ?? "all";
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "feed:search",
+    parts: ["feed", "search", input.query, channel, before],
+    params: { query: input.query, channel, before },
+  });
+}
+
+export function inboxThreadsScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  status?: string;
+  mailbox?: string;
+  participant?: string;
+  participantScope?: string;
+  query?: string;
+  hasAttachment?: boolean;
+  before?: string;
+}): CacheScope {
+  const status = input.status ?? "default";
+  const mailbox = input.mailbox ?? "default";
+  const participant = input.participant ?? "default";
+  const participantScope = input.participantScope ?? "default";
+  const query = input.query ?? "default";
+  const hasAttachment = input.hasAttachment ?? false;
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "inbox:threads",
+    parts: [
+      "inbox",
+      "threads",
+      status,
+      mailbox,
+      participant,
+      participantScope,
+      query,
+      String(hasAttachment),
+      before,
+      input.actorKey,
+    ],
+    params: {
+      status,
+      mailbox,
+      participant,
+      participantScope,
+      query,
+      hasAttachment,
+      before,
+    },
+  });
+}
+
+export function inboxMessagesScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  threadId: string;
+  query?: string;
+  hasAttachment?: boolean;
+  before?: string;
+}): CacheScope {
+  const query = input.query ?? "default";
+  const hasAttachment = input.hasAttachment ?? false;
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "inbox:messages",
+    parts: [
+      "inbox",
+      "messages",
+      input.threadId,
+      query,
+      String(hasAttachment),
+      before,
+      input.actorKey,
+    ],
+    params: { threadId: input.threadId, query, hasAttachment, before },
+  });
+}
+
+export function ownedPostsScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  channelId: string;
+  before?: string;
+}): CacheScope {
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "posts:owned",
+    parts: ["posts", "owned", input.channelId, before],
+    params: { channelId: input.channelId, before },
+  });
+}
+
+export function publicPostsScope(input: {
+  context: CommandContext;
+  publicHandle: string;
+  channelName: string;
+  before?: string;
+}): CacheScope {
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: PUBLIC_ACTOR_KEY,
+    resource: "posts:public",
+    parts: ["posts", "public", input.publicHandle, input.channelName, before],
+    params: {
+      publicHandle: input.publicHandle,
+      channelName: input.channelName,
+      before,
+    },
+  });
+}
+
+export function sharedPostsScope(input: {
+  context: CommandContext;
+  shareToken: string;
+  before?: string;
+}): CacheScope {
+  const shareTokenHash = hashValue(input.shareToken);
+  const before = input.before ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: SHARED_ACTOR_KEY,
+    resource: "posts:shared",
+    parts: ["posts", "shared", shareTokenHash, before],
+    params: { shareTokenHash, before },
+  });
+}
+
+export function hashValue(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function actorKey(actor: WhoamiActor): string {
+  if (actor.type === "user") {
+    return `user:${actor.id}:${actor.scope ?? "master"}`;
+  }
+
+  return `channel:${actor.id}`;
+}
+
+function scoped(input: {
+  context: CommandContext;
+  actorKey: string;
+  resource: string;
+  parts: string[];
+  params: Record<string, unknown>;
+}): CacheScope {
+  const prefix = [
+    "v1",
+    normalizePart(input.context.profile.baseUrl),
+    normalizePart(input.context.profileName),
+    normalizePart(input.actorKey),
+  ];
+  const scopeKey = [...prefix, ...input.parts.map(normalizePart)].join(":");
+
+  return {
+    scopeKey,
+    resource: input.resource,
+    params: input.params,
+    actorKey: input.actorKey,
+  };
+}
+
+function normalizePart(value: string): string {
+  return encodeURIComponent(value);
+}
+
+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/client.ts

@@ -31,6 +31,7 @@ import type {
   MailboxFilter,
   MessageAttachmentAttributes,
   MessageAttributes,
+  ParticipantScope,
   PostAttributes,
   ProfileConfig,
   ShareTokenResponse,
@@ -535,6 +536,7 @@ export class ClankmatesClient {
     channelId: string;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
   }) {
@@ -542,6 +544,7 @@ export class ClankmatesClient {
       withQuery(`${API_PREFIX}/channels/${input.channelId}/posts`, {
         order: input.order,
         since: input.since,
+        before: input.before,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -556,6 +559,7 @@ export class ClankmatesClient {
     channelName: string;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
   }) {
@@ -565,6 +569,7 @@ export class ClankmatesClient {
         {
           order: input.order,
           since: input.since,
+          before: input.before,
           "page[limit]": input.limit,
           "page[after]": input.cursor,
         },
@@ -577,6 +582,7 @@ export class ClankmatesClient {
     token: string;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
   }) {
@@ -584,6 +590,7 @@ export class ClankmatesClient {
       withQuery(`${API_PREFIX}/shares/channels/${encodeURIComponent(input.token)}/posts`, {
         order: input.order,
         since: input.since,
+        before: input.before,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -674,6 +681,7 @@ export class ClankmatesClient {
     channelId?: string;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
   }) {
@@ -682,6 +690,7 @@ export class ClankmatesClient {
         channel_id: input.channelId,
         order: input.order,
         since: input.since,
+        before: input.before,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -696,6 +705,7 @@ export class ClankmatesClient {
     channelId?: string;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
   }) {
@@ -705,6 +715,7 @@ export class ClankmatesClient {
         channel_id: input.channelId,
         order: input.order,
         since: input.since,
+        before: input.before,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -731,8 +742,13 @@ export class ClankmatesClient {
     mailbox?: MailboxFilter;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
+    participant?: string;
+    participantScope?: ParticipantScope;
+    query?: string;
+    hasAttachment?: boolean;
     channelToken?: string;
   } = {}) {
     return this.requestCollection<ThreadAttributes>(
@@ -741,6 +757,11 @@ export class ClankmatesClient {
         mailbox: input.mailbox,
         order: input.order,
         since: input.since,
+        before: input.before,
+        participant: input.participant,
+        participant_scope: input.participantScope,
+        query: input.query,
+        has_attachment: input.hasAttachment,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -754,6 +775,10 @@ export class ClankmatesClient {
     since: string;
     status?: ThreadStatusFilter;
     mailbox?: MailboxFilter;
+    participant?: string;
+    participantScope?: ParticipantScope;
+    query?: string;
+    hasAttachment?: boolean;
     channelToken?: string;
   }) {
     return this.requestAction<ChangeCheckResponse>(
@@ -761,6 +786,10 @@ export class ClankmatesClient {
         since: input.since,
         status: input.status,
         mailbox: input.mailbox,
+        participant: input.participant,
+        participant_scope: input.participantScope,
+        query: input.query,
+        has_attachment: input.hasAttachment,
       }),
       {
         token: this.resolveInboxReadToken(input.channelToken),
@@ -778,14 +807,20 @@ export class ClankmatesClient {
     threadId: string;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
+    query?: string;
+    hasAttachment?: boolean;
     channelToken?: string;
   }) {
     return this.requestCollection<MessageAttributes>(
       withQuery(`${API_PREFIX}/threads/${input.threadId}/messages`, {
         order: input.order,
         since: input.since,
+        before: input.before,
+        query: input.query,
+        has_attachment: input.hasAttachment,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -798,11 +833,15 @@ export class ClankmatesClient {
   async checkThreadMessageChanges(input: {
     threadId: string;
     since: string;
+    query?: string;
+    hasAttachment?: boolean;
     channelToken?: string;
   }) {
     return this.requestAction<ChangeCheckResponse>(
       withQuery(`${API_PREFIX}/threads/${input.threadId}/messages/changes`, {
         since: input.since,
+        query: input.query,
+        has_attachment: input.hasAttachment,
       }),
       {
         token: this.resolveInboxReadToken(input.channelToken),
@@ -1132,7 +1171,7 @@ function looksLikeUuid(value: string): boolean {
 
 function withQuery(
   path: string,
-  params: Record<string, string | number | undefined>,
+  params: Record<string, string | number | boolean | undefined>,
 ): string {
   const search = new URLSearchParams();