Skip to content
Python
2.7 KB
Raw Blame
/** Memory-add contract: the `POST /api/v2/memories` body, its receipt check and
 * the addition status path.
 *
 * Core takes exactly `request_id`, `text`, `scope`; the CLI and the UI both
 * hard-code `scope: "all-apps"`, so keeping the body here means both surfaces
 * send the same three fields. A receipt is validated before it becomes state —
 * the evidence id must be a UUID and the state must be one of the known
 * states — so a malformed 200 is never rendered as a real addition.
 *
 * Dependency-free (contracts types only) so it can move into a shared package.
 */
import type { MemoryAddInput, MemoryAddReceipt } from "@one-memory/contracts";

export class MemoryAddInputError extends Error {}

const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
const ADD_STATES = [
  "waiting_for_model",
  "waiting_for_permission",
  "pending",
  "running",
  "failed",
  "ready",
  "no_memories",
] as const;

export interface MemoryAddRequest {
  path: "/api/v2/memories";
  body: { request_id: string; text: string; scope: "all-apps" };
}

/** The exact three-field body Core accepts; scope is fixed, not caller-supplied. */
export function buildMemoryAddRequest(input: MemoryAddInput): MemoryAddRequest {
  if (typeof input.request_id !== "string" || !UUID.test(input.request_id))
    throw new MemoryAddInputError("request_id_invalid");
  if (typeof input.text !== "string" || input.text.trim().length === 0)
    throw new MemoryAddInputError("text_required");
  return {
    path: "/api/v2/memories",
    body: { request_id: input.request_id, text: input.text, scope: "all-apps" },
  };
}

/** Where the status of one addition is read, keyed by its request id. */
export function memoryAddStatusPath(requestId: string): string {
  if (typeof requestId !== "string" || !UUID.test(requestId))
    throw new MemoryAddInputError("request_id_invalid");
  return `/api/v2/memories/additions/${requestId}`;
}

/**
 * Validate a memory-add receipt before it becomes UI state.
 *
 * Returns null for a malformed body; callers must treat that as an unknown
 * result rather than a saved memory.
 */
export function parseMemoryAddReceipt(value: unknown): MemoryAddReceipt | null {
  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
  const receipt = value as Record<string, unknown>;
  if (
    typeof receipt.evidence_id !== "string" ||
    !UUID.test(receipt.evidence_id) ||
    typeof receipt.state !== "string" ||
    !(ADD_STATES as readonly string[]).includes(receipt.state) ||
    receipt.scope !== "all-apps"
  )
    return null;
  if (
    !Array.isArray(receipt.memory_ids) ||
    receipt.memory_ids.some((id) => typeof id !== "string")
  )
    return null;
  return value as MemoryAddReceipt;
}