@hraness/ghostget 0.17.2

package/src/beeper-client-types.ts

@@ -0,0 +1,169 @@
+/** Self-contained DTO types for the side-effect-free public Beeper client. */
+
+export type BeeperContactInteractionAccount = Readonly<{
+  accountId: string;
+  accountProviderId: string;
+  network: string;
+  selfParticipantId: string;
+  selfParticipantProviderId: string;
+  observedAt: string;
+}>;
+
+export type BeeperContactInteraction = Readonly<{
+  accountId: string;
+  accountProviderId: string;
+  contactId: string;
+  contactProviderId: string;
+  network: string;
+  sentCount: number;
+  receivedCount: number;
+  interactionCount: number;
+  conversationCount: number;
+  firstInteractionAt: string;
+  lastInteractionAt: string;
+  reciprocal: boolean;
+  completeness: "lower-bound";
+  provenance: Readonly<{
+    sourceId: "beeper-local";
+    sourceVersion: "1.1.0";
+    providerId: "beeper";
+    providerVersion: string;
+    observedAt: string;
+  }>;
+}>;
+
+export type BeeperContactInteractionSummary = Readonly<{
+  schemaVersion: 1;
+  format: "wrench.contact-interaction-summary";
+  transform: Readonly<{
+    id: "beeper-direct-contact-interactions";
+    version: 1;
+    sourceVersion: "1.1.0";
+  }>;
+  source: Readonly<{ id: "beeper-local"; version: "1.1.0" }>;
+  provider: Readonly<{ id: "beeper"; version: string }>;
+  observedAt: string | null;
+  scope: Readonly<{
+    conversations: "complete-direct-only";
+    messages: "current-direction-known-only";
+  }>;
+  completeness: Readonly<{
+    kind: "lower-bound";
+    sourceKind: "bounded-local" | "truncated" | "unknown";
+    reason: string | null;
+    observedFrom: string | null;
+    observedThrough: string | null;
+  }>;
+  warnings: readonly string[];
+  privacy: Readonly<{
+    messageBodies: "excluded";
+    attachments: "excluded";
+    reactions: "excluded";
+    media: "excluded";
+    groupMessages: "excluded";
+    localPaths: "excluded";
+    credentials: "excluded";
+  }>;
+  counts: Readonly<{
+    accounts: number;
+    directRelationships: number;
+    directConversations: number;
+    interactions: number;
+    sent: number;
+    received: number;
+  }>;
+  accounts: readonly BeeperContactInteractionAccount[];
+  interactions: readonly BeeperContactInteraction[];
+  integrity: Readonly<{
+    algorithm: "sha256";
+    summarySha256: string;
+  }>;
+}>;
+
+export type BeeperContactInteractionExportBounds = Readonly<{
+  limitChats: number | null;
+  limitMessages: number | null;
+  maxParticipants: number | null;
+}>;
+
+export type BeeperContactInteractionExportReceipt = Readonly<{
+  schemaVersion: 1;
+  format: "wrench.beeper-contact-interaction-export-receipt";
+  runId: string;
+  operation: "beeper.export-contact-interactions";
+  status: "succeeded";
+  transport: "linked-device";
+  implementation: Readonly<{
+    producer: Readonly<{
+      package: "@hraness/ghostget";
+      version: "0.17.2";
+    }>;
+    officialCli: Readonly<{
+      implementation: "github.com/beeper/cli";
+      version: "0.6.2";
+      commit: "a416af06023449a87312dc11e54643fd9dc94b8c";
+      platform: "darwin-arm64";
+      binarySha256: "48aa895449129c793a212ea19f69a534adc34a8adc4037ca1d7da9e648716425";
+    }>;
+  }>;
+  startedAt: string;
+  finishedAt: string;
+  auth: Readonly<{
+    id: string;
+    kind: "linked-device-store";
+    provider: "beeper";
+    identitySha256: string;
+  }>;
+  bounds: BeeperContactInteractionExportBounds;
+  source: BeeperContactInteractionSummary["source"];
+  provider: BeeperContactInteractionSummary["provider"];
+  transform: BeeperContactInteractionSummary["transform"];
+  completeness: BeeperContactInteractionSummary["completeness"];
+  counts: BeeperContactInteractionSummary["counts"];
+  output: Readonly<{
+    schemaVersion: 1;
+    format: "wrench.contact-interaction-summary";
+    summarySha256: string;
+  }>;
+  privacy: Readonly<{
+    messageBodies: "excluded";
+    attachments: "excluded";
+    reactions: "excluded";
+    media: "excluded";
+    localPaths: "excluded";
+    credentials: "excluded";
+  }>;
+  integrity: Readonly<{
+    algorithm: "sha256";
+    receiptSha256: string;
+  }>;
+}>;
+
+export type BeeperContactInteractionExportResult = Readonly<{
+  receipt: BeeperContactInteractionExportReceipt;
+  output: BeeperContactInteractionSummary;
+}>;
+
+export type BeeperContactInteractionClientRequest = Readonly<{
+  authId: string;
+  limitChats?: number;
+  limitMessages?: number;
+  maxParticipants?: number;
+}>;
+
+export type BeeperContactInteractionClientOptions = Readonly<{
+  environment?: Readonly<Record<string, string | undefined>>;
+}>;
+
+export declare function exportBeeperContactInteractionsSync(
+  request: BeeperContactInteractionClientRequest,
+  options?: BeeperContactInteractionClientOptions,
+): BeeperContactInteractionExportResult;
+
+export declare function parseBeeperContactInteractionExportResult(
+  value: unknown,
+): BeeperContactInteractionExportResult;
+
+export declare function parseBeeperContactInteractionSummary(
+  value: unknown,
+): BeeperContactInteractionSummary;

package/src/beeper-client.ts

@@ -0,0 +1,250 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { types as nodeTypes } from "node:util";
+
+import {
+  BEEPER_CONTACT_INTERACTION_WIRE_MAX_BYTES,
+  parseBeeperContactInteractionExportResult,
+} from "./beeper-contact-interactions";
+import type {
+  BeeperContactInteractionClientOptions,
+  BeeperContactInteractionClientRequest,
+  BeeperContactInteractionExportResult,
+} from "./beeper-client-types";
+
+const MAX_STDERR_BYTES = 8 * 1024;
+const PROCESS_TIMEOUT_MS = 6 * 60 * 60 * 1_000 + 60_000;
+
+function fail(message: string): never {
+  throw new Error(`Ghostget Beeper client: ${message}`);
+}
+
+function cliSourcePath(): string {
+  const besideSource = fileURLToPath(new URL("./cli.ts", import.meta.url));
+  if (existsSync(besideSource)) return besideSource;
+  const packagedSource = fileURLToPath(new URL("../src/cli.ts", import.meta.url));
+  if (existsSync(packagedSource)) return packagedSource;
+  return fail("the installed Ghostget CLI source is unavailable");
+}
+
+function requireBunRuntime(): void {
+  if (typeof process.versions.bun !== "string") {
+    fail("@hraness/ghostget/beeper requires Bun to run the installed Ghostget CLI");
+  }
+}
+
+function plainDataObject(
+  value: unknown,
+  label: string,
+): Readonly<Record<string, PropertyDescriptor>> {
+  if (
+    typeof value !== "object"
+    || value === null
+    || Array.isArray(value)
+    || nodeTypes.isProxy(value)
+    || (
+      Object.getPrototypeOf(value) !== Object.prototype
+      && Object.getPrototypeOf(value) !== null
+    )
+  ) return fail(`${label} must use a plain, non-proxy object`);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const keys = Reflect.ownKeys(descriptors);
+  if (keys.some((key) => typeof key !== "string")) {
+    return fail(`${label} has unsupported symbol fields`);
+  }
+  for (const key of keys as string[]) {
+    const descriptor = descriptors[key];
+    if (descriptor === undefined || !descriptor.enumerable || !("value" in descriptor)) {
+      return fail(`${label} must contain only enumerable data properties`);
+    }
+  }
+  return descriptors;
+}
+
+function positiveInteger(
+  value: unknown,
+  label: string,
+  maximum: number,
+): number | undefined {
+  if (value === undefined) return undefined;
+  if (
+    typeof value !== "number"
+    || !Number.isSafeInteger(value)
+    || value < 1
+    || value > maximum
+  ) return fail(`${label} must be an integer from 1 through ${String(maximum)}`);
+  return value;
+}
+
+function prepareRequest(
+  value: BeeperContactInteractionClientRequest,
+): Required<Pick<BeeperContactInteractionClientRequest, "authId">>
+  & Omit<BeeperContactInteractionClientRequest, "authId"> {
+  const descriptors = plainDataObject(value, "request");
+  const keys = Object.keys(descriptors);
+  const allowed = new Set([
+    "authId", "limitChats", "limitMessages", "maxParticipants",
+  ]);
+  if (!keys.includes("authId") || keys.some((key) => !allowed.has(key))) {
+    return fail("request contains unsupported or missing fields");
+  }
+  const authId = descriptors.authId?.value as unknown;
+  if (
+    typeof authId !== "string"
+    || !/^[a-z][a-z0-9-]{0,127}$/u.test(authId)
+  ) return fail("authId must be lowercase kebab text");
+  const limitChats = positiveInteger(
+    descriptors.limitChats?.value,
+    "limitChats",
+    100_000,
+  );
+  const limitMessages = positiveInteger(
+    descriptors.limitMessages?.value,
+    "limitMessages",
+    1_000_000,
+  );
+  const maxParticipants = positiveInteger(
+    descriptors.maxParticipants?.value,
+    "maxParticipants",
+    2_000,
+  );
+  return Object.freeze({
+    authId,
+    ...(limitChats === undefined ? {} : { limitChats }),
+    ...(limitMessages === undefined ? {} : { limitMessages }),
+    ...(maxParticipants === undefined ? {} : { maxParticipants }),
+  });
+}
+
+function environmentName(value: string): string {
+  if (value.length < 1 || value.includes("=") || value.includes("\0")) {
+    return fail("environment name is malformed");
+  }
+  return value;
+}
+
+function prepareEnvironment(
+  value: BeeperContactInteractionClientOptions["environment"],
+): Readonly<Record<string, string>> {
+  const environment = Object.create(null) as Record<string, string>;
+  for (const [key, item] of Object.entries(process.env)) {
+    if (typeof item === "string") environment[key] = item;
+  }
+  if (value === undefined) return Object.freeze(environment);
+  const descriptors = plainDataObject(value, "environment");
+  for (const key of Object.keys(descriptors).sort()) {
+    const name = environmentName(key);
+    const item = descriptors[key]!.value as unknown;
+    if (item === undefined) delete environment[name];
+    else if (typeof item !== "string" || item.includes("\0")) {
+      return fail("environment value is malformed");
+    } else environment[name] = item;
+  }
+  return Object.freeze(environment);
+}
+
+function prepareOptions(
+  value: BeeperContactInteractionClientOptions,
+): Readonly<Record<string, string>> {
+  const descriptors = plainDataObject(value, "options");
+  const keys = Object.keys(descriptors);
+  if (keys.some((key) => key !== "environment")) {
+    return fail("options contain an unsupported field");
+  }
+  return prepareEnvironment(descriptors.environment?.value as
+    BeeperContactInteractionClientOptions["environment"]);
+}
+
+function boundedError(value: unknown): string {
+  const text = typeof value === "string" ? value.trim() : "";
+  const bytes = Buffer.from(text, "utf8");
+  if (bytes.byteLength <= MAX_STDERR_BYTES) return text;
+  return `${bytes.subarray(0, MAX_STDERR_BYTES).toString("utf8").trim()}…`;
+}
+
+/**
+ * Execute Ghostget's installed, reviewed body-free Beeper export synchronously.
+ * The executable is package-owned, not caller-selected. Progress is inherited
+ * on stderr and the returned value has passed the exact public artifact parser.
+ */
+export function exportBeeperContactInteractionsSync(
+  requestValue: BeeperContactInteractionClientRequest,
+  optionsValue: BeeperContactInteractionClientOptions = {},
+): BeeperContactInteractionExportResult {
+  requireBunRuntime();
+  const request = prepareRequest(requestValue);
+  const environment = prepareOptions(optionsValue);
+  const result = spawnSync(process.execPath, [
+    cliSourcePath(),
+    "beeper",
+    "export-contact-interactions",
+    "--auth",
+    request.authId,
+    ...(request.limitChats === undefined
+      ? []
+      : ["--limit-chats", String(request.limitChats)]),
+    ...(request.limitMessages === undefined
+      ? []
+      : ["--limit-messages", String(request.limitMessages)]),
+    ...(request.maxParticipants === undefined
+      ? []
+      : ["--max-participants", String(request.maxParticipants)]),
+    "--json",
+  ], {
+    cwd: process.cwd(),
+    env: environment,
+    encoding: "utf8",
+    maxBuffer: BEEPER_CONTACT_INTERACTION_WIRE_MAX_BYTES,
+    timeout: PROCESS_TIMEOUT_MS,
+    stdio: ["ignore", "pipe", "inherit"],
+  });
+  if (result.error !== undefined) return fail("summary process could not complete");
+  if (result.status !== 0 || typeof result.stdout !== "string") {
+    const stderr = boundedError(result.stderr);
+    return fail(stderr.length === 0 ? "summary process failed" : stderr);
+  }
+  if (
+    Buffer.byteLength(result.stdout, "utf8")
+    > BEEPER_CONTACT_INTERACTION_WIRE_MAX_BYTES
+  ) {
+    return fail("summary response exceeded its byte bound");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(result.stdout) as unknown;
+  } catch {
+    return fail("summary response was not JSON");
+  }
+  const resultValue = parseBeeperContactInteractionExportResult(parsed);
+  if (resultValue.receipt.auth.id !== request.authId) {
+    return fail("summary receipt auth does not match its request");
+  }
+  const expectedBounds = Object.freeze({
+    limitChats: request.limitChats ?? null,
+    limitMessages: request.limitMessages ?? null,
+    maxParticipants: request.maxParticipants ?? null,
+  });
+  if (
+    resultValue.receipt.bounds.limitChats !== expectedBounds.limitChats
+    || resultValue.receipt.bounds.limitMessages !== expectedBounds.limitMessages
+    || resultValue.receipt.bounds.maxParticipants !== expectedBounds.maxParticipants
+  ) return fail("summary receipt bounds do not match its request");
+  return resultValue;
+}
+
+export {
+  parseBeeperContactInteractionExportResult,
+  parseBeeperContactInteractionSummary,
+} from "./beeper-contact-interactions";
+
+export type {
+  BeeperContactInteraction,
+  BeeperContactInteractionAccount,
+  BeeperContactInteractionClientOptions,
+  BeeperContactInteractionClientRequest,
+  BeeperContactInteractionExportBounds,
+  BeeperContactInteractionExportReceipt,
+  BeeperContactInteractionExportResult,
+  BeeperContactInteractionSummary,
+} from "./beeper-client-types";

package/src/beeper-contact-interactions-cli.ts

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+
+import type { GhostgetAuth } from "./auth";
+import { canonicalJson, sha256 } from "./canonical-json";
+import {
+  createBeeperContactInteractionExportResult,
+  encodeBeeperContactInteractionExportResult,
+  summarizeBeeperContactInteractions,
+  type BeeperContactInteractionExportResult,
+  type BeeperContactInteractionProgress,
+  type BeeperContactInteractionSummary,
+} from "./beeper-contact-interactions";
+
+export { encodeBeeperContactInteractionExportResult };
+import {
+  acquireBeeperMessageLikeMeExportAdmission,
+  recoverBeeperMessageLikeMeDirectoryLeases,
+  releaseBeeperMessageLikeMeExportAdmission,
+} from "./beeper-message-like-me-recovery";
+import {
+  createBeeperMessageLikeMeSource,
+  type BeeperMessageLikeMeProgress,
+  type BeeperMessageLikeMeSourceCoordinate,
+  type BeeperMessageLikeMeSourceLimits,
+} from "./beeper-message-like-me-source";
+
+const CLEANUP_HEARTBEAT_MS = 30_000;
+
+export type BeeperContactInteractionCliProgress =
+  | BeeperMessageLikeMeProgress
+  | BeeperContactInteractionProgress;
+
+export type BeeperContactInteractionCliRequest = Readonly<{
+  auth: GhostgetAuth;
+  limits?: BeeperMessageLikeMeSourceLimits;
+  environment?: Readonly<Record<string, string | undefined>>;
+  signal?: AbortSignal;
+  onProgress?: (progress: BeeperContactInteractionCliProgress) => void;
+}>;
+
+/** Preserve the exact platform identity published by the schema-1 receipt. */
+export function assertBeeperContactInteractionExportRuntime(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): void {
+  if (platform !== "darwin" || arch !== "arm64") {
+    throw new Error(
+      "Beeper contact interaction summary: schema-1 export requires the pinned darwin/arm64 Beeper CLI artifact",
+    );
+  }
+}
+
+async function disposeSource(
+  dispose: (() => Promise<void>) | undefined,
+  onProgress: BeeperContactInteractionCliRequest["onProgress"],
+): Promise<void> {
+  if (dispose === undefined) return;
+  const startedAt = Date.now();
+  const report = (): void => onProgress?.(Object.freeze({
+    phase: "private-cleanup",
+    elapsedSeconds: Math.max(0, Math.floor((Date.now() - startedAt) / 1_000)),
+  }));
+  report();
+  const heartbeat = onProgress === undefined
+    ? undefined
+    : setInterval(report, CLEANUP_HEARTBEAT_MS);
+  try {
+    await dispose();
+  } finally {
+    if (heartbeat !== undefined) clearInterval(heartbeat);
+  }
+}
+
+/**
+ * Run the admitted sequential Beeper history source and return only its
+ * content-free direct-contact interaction summary. Raw private shards are
+ * operation-owned and removed before this function resolves.
+ */
+export async function exportBeeperContactInteractionsFromAuth(
+  request: BeeperContactInteractionCliRequest,
+): Promise<BeeperContactInteractionExportResult> {
+  assertBeeperContactInteractionExportRuntime();
+  const startedAt = new Date().toISOString();
+  try {
+    const environment = request.environment ?? process.env;
+    request.onProgress?.(Object.freeze({ phase: "recovery-started" }));
+    const admission = acquireBeeperMessageLikeMeExportAdmission({ environment });
+    try {
+      const recovery = await recoverBeeperMessageLikeMeDirectoryLeases({
+        environment,
+      });
+      if (recovery.active > 0 || recovery.indeterminate > 0) {
+        throw new Error(
+          "Beeper contact interaction summary: another export is active or prior private export recovery is indeterminate",
+        );
+      }
+      request.onProgress?.(Object.freeze({
+        phase: "recovery-completed",
+        recovered: recovery.recovered,
+        published: recovery.published,
+      }));
+      const coordinates = new WeakMap<object, BeeperMessageLikeMeSourceCoordinate>();
+      const source = createBeeperMessageLikeMeSource({
+        auth: request.auth,
+        ...(request.limits === undefined ? {} : { limits: request.limits }),
+        ...(request.environment === undefined
+          ? {}
+          : { environment: request.environment }),
+        ...(request.signal === undefined ? {} : { signal: request.signal }),
+        ...(request.onProgress === undefined
+          ? {}
+          : { onProgress: request.onProgress }),
+        onRecordCoordinate: (record, coordinate) => {
+          coordinates.set(record, coordinate);
+        },
+      });
+      let summary: BeeperContactInteractionSummary | undefined;
+      let operationError: unknown;
+      try {
+        summary = await summarizeBeeperContactInteractions({
+          source,
+          coordinateForRecord: (record) => (
+            typeof record === "object" && record !== null
+              ? coordinates.get(record)
+              : undefined
+          ),
+          ...(request.onProgress === undefined
+            ? {}
+            : { onProgress: request.onProgress }),
+          ...(request.signal === undefined ? {} : { signal: request.signal }),
+        });
+      } catch (error) {
+        operationError = error;
+      }
+      try {
+        await disposeSource(
+          source.dispose === undefined
+            ? undefined
+            : () => source.dispose!(false),
+          request.onProgress,
+        );
+      } catch (cleanupError) {
+        if (operationError !== undefined) {
+          throw new AggregateError(
+            [operationError, cleanupError],
+            "Beeper contact interaction summary and private cleanup both failed",
+          );
+        }
+        throw cleanupError;
+      }
+      if (operationError !== undefined) throw operationError;
+      if (summary === undefined) {
+        throw new Error("Beeper contact interaction summary: result disappeared");
+      }
+      return createBeeperContactInteractionExportResult({
+        runId: randomUUID(),
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        authId: request.auth.id,
+        authIdentitySha256: sha256(canonicalJson(request.auth)),
+        bounds: Object.freeze({
+          limitChats: request.limits?.limitChats ?? null,
+          limitMessages: request.limits?.limitMessages ?? null,
+          maxParticipants: request.limits?.maxParticipants ?? null,
+        }),
+        output: summary,
+      });
+    } finally {
+      releaseBeeperMessageLikeMeExportAdmission(admission);
+    }
+  } catch (error) {
+    if (
+      error instanceof Error
+      && /^(?:Beeper |Message Like Me |pinned Beeper CLI )/u.test(error.message)
+    ) throw error;
+    throw new Error(
+      "Beeper contact interaction summary: private local operation failed",
+    );
+  }
+}