@clankmates/cli 0.10.3 → 0.11.1

package/src/lib/args.ts

@@ -49,6 +49,12 @@ const CLI_OPTIONS = {
   "schema-stdin": { type: "boolean" },
   limit: { type: "string" },
   cursor: { type: "string" },
+  order: { type: "string" },
+  since: { type: "string" },
+  sinceCache: { type: "boolean" },
+  "since-cache": { type: "boolean" },
+  saveCache: { type: "boolean" },
+  "save-cache": { type: "boolean" },
   status: { type: "string" },
   mailbox: { type: "string" },
 } as const;

package/src/lib/cache.ts

@@ -0,0 +1,499 @@
+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;
+}): CacheScope {
+  const channel = input.channelId ?? "all";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "feed:my",
+    parts: ["feed", "my", channel],
+    params: { channel },
+  });
+}
+
+export function feedSearchScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  query: string;
+  channelId?: string;
+}): CacheScope {
+  const channel = input.channelId ?? "all";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "feed:search",
+    parts: ["feed", "search", input.query, channel],
+    params: { query: input.query, channel },
+  });
+}
+
+export function inboxThreadsScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  status?: string;
+  mailbox?: string;
+}): CacheScope {
+  const status = input.status ?? "default";
+  const mailbox = input.mailbox ?? "default";
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "inbox:threads",
+    parts: ["inbox", "threads", status, mailbox, input.actorKey],
+    params: { status, mailbox },
+  });
+}
+
+export function inboxMessagesScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  threadId: string;
+}): CacheScope {
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "inbox:messages",
+    parts: ["inbox", "messages", input.threadId, input.actorKey],
+    params: { threadId: input.threadId },
+  });
+}
+
+export function ownedPostsScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  channelId: string;
+}): CacheScope {
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "posts:owned",
+    parts: ["posts", "owned", input.channelId],
+    params: { channelId: input.channelId },
+  });
+}
+
+export function publicPostsScope(input: {
+  context: CommandContext;
+  publicHandle: string;
+  channelName: string;
+}): CacheScope {
+  return scoped({
+    context: input.context,
+    actorKey: PUBLIC_ACTOR_KEY,
+    resource: "posts:public",
+    parts: ["posts", "public", input.publicHandle, input.channelName],
+    params: {
+      publicHandle: input.publicHandle,
+      channelName: input.channelName,
+    },
+  });
+}
+
+export function sharedPostsScope(input: {
+  context: CommandContext;
+  shareToken: string;
+}): CacheScope {
+  const shareTokenHash = hashValue(input.shareToken);
+  return scoped({
+    context: input.context,
+    actorKey: SHARED_ACTOR_KEY,
+    resource: "posts:shared",
+    parts: ["posts", "shared", shareTokenHash],
+    params: { shareTokenHash },
+  });
+}
+
+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

@@ -21,11 +21,13 @@ import type {
   ChannelKeyRevokeResponse,
   ChannelPinResponse,
   ChannelPublicationResponse,
+  ChangeCheckResponse,
   ExternalEmailAcceptance,
   ExternalEmailIntakeAttributes,
   InboxRecipient,
   InboxSender,
   IdResponse,
+  LatestFirstOrder,
   MailboxFilter,
   MessageAttachmentAttributes,
   MessageAttributes,
@@ -533,9 +535,13 @@ export class ClankmatesClient {
     channelId: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/channels/${input.channelId}/posts`, {
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -550,11 +556,15 @@ export class ClankmatesClient {
     channelName: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(
         `${API_PREFIX}/public/users/${encodeURIComponent(input.publicHandle)}/channels/${encodeURIComponent(input.channelName)}/posts`,
         {
+          order: input.order,
+          since: input.since,
           "page[limit]": input.limit,
           "page[after]": input.cursor,
         },
@@ -567,9 +577,13 @@ export class ClankmatesClient {
     token: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/shares/channels/${encodeURIComponent(input.token)}/posts`, {
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -656,10 +670,18 @@ export class ClankmatesClient {
     });
   }
 
-  async myFeed(input: { channelId?: string; limit?: number; cursor?: string }) {
+  async myFeed(input: {
+    channelId?: string;
+    limit?: number;
+    cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
+  }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/feeds/my`, {
         channel_id: input.channelId,
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -674,11 +696,15 @@ export class ClankmatesClient {
     channelId?: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/feeds/my/search`, {
         query: input.query,
         channel_id: input.channelId,
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -688,17 +714,33 @@ export class ClankmatesClient {
     );
   }
 
+  async checkMyFeedChanges(input: { since: string; channelId?: string }) {
+    return this.requestAction<ChangeCheckResponse>(
+      withQuery(`${API_PREFIX}/feeds/my/changes`, {
+        since: input.since,
+        channel_id: input.channelId,
+      }),
+      {
+        token: requireOwnerReadToken(this.profile),
+      },
+    );
+  }
+
   async listInboxThreads(input: {
     status?: ThreadStatusFilter;
     mailbox?: MailboxFilter;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
     channelToken?: string;
   } = {}) {
     return this.requestCollection<ThreadAttributes>(
       withQuery(`${API_PREFIX}/threads`, {
         status: input.status,
         mailbox: input.mailbox,
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -708,6 +750,24 @@ export class ClankmatesClient {
     );
   }
 
+  async checkInboxThreadChanges(input: {
+    since: string;
+    status?: ThreadStatusFilter;
+    mailbox?: MailboxFilter;
+    channelToken?: string;
+  }) {
+    return this.requestAction<ChangeCheckResponse>(
+      withQuery(`${API_PREFIX}/threads/changes`, {
+        since: input.since,
+        status: input.status,
+        mailbox: input.mailbox,
+      }),
+      {
+        token: this.resolveInboxReadToken(input.channelToken),
+      },
+    );
+  }
+
   async getThread(threadId: string, channelToken?: string) {
     return this.requestResource<ThreadAttributes>(`${API_PREFIX}/threads/${threadId}`, {
       token: this.resolveInboxReadToken(channelToken),
@@ -718,10 +778,14 @@ export class ClankmatesClient {
     threadId: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
     channelToken?: string;
   }) {
     return this.requestCollection<MessageAttributes>(
       withQuery(`${API_PREFIX}/threads/${input.threadId}/messages`, {
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -731,6 +795,21 @@ export class ClankmatesClient {
     );
   }
 
+  async checkThreadMessageChanges(input: {
+    threadId: string;
+    since: string;
+    channelToken?: string;
+  }) {
+    return this.requestAction<ChangeCheckResponse>(
+      withQuery(`${API_PREFIX}/threads/${input.threadId}/messages/changes`, {
+        since: input.since,
+      }),
+      {
+        token: this.resolveInboxReadToken(input.channelToken),
+      },
+    );
+  }
+
   async listMessageAttachments(input: {
     messageId: string;
     limit?: number;