​

Per-user state persistence model

​

The problem with browser-bound state

• A draft saved on the office workstation did not exist on the laptop at home.
• Clearing site data, a private-browsing window, or a fresh browser profile erased the history.
• On a shared workstation, the next operator to sign in saw the previous operator’s drafts, or lost their own.

​

What the platform now persists per surface

• saved_ai_campaign_drafts
• generated_reports
• recommendations_tester_draft
• inbox_show_archived_tags (your Inbox archived-tags toggle)
• inbox_signature (your Inbox reply signature)

• No schema change was required. The preferences column already existed and already held inbox_signature and inbox_show_archived_tags, so each new surface shipped without a migration window and without touching unrelated data.
• Writes never clobber each other. Every update merges exactly its own key into the record and leaves every sibling key untouched, so saving your report history cannot erase a draft, a signature, or a toggle.
• The pattern is a template. If you build tooling on the API that keeps per-operator state, treat these endpoints as the model: one namespaced key per surface, merged writes, and defensive reads.

​

The GET/PUT shape

​

Lifting state you already saved in the browser

​

Sync then clear

"use client";

import { useEffect, useRef } from "react";

const LEGACY_REPORTS_KEY = "orbit-generated-reports-v2";

function readLocal(): unknown[] {
  try {
    const parsed: unknown = JSON.parse(
      window.localStorage.getItem(LEGACY_REPORTS_KEY) ?? "[]",
    );
    return Array.isArray(parsed) ? parsed : [];
  } catch {
    return [];
  }
}

/** Lift a local report history into the account, then clear the local copy. */
export function useLiftLocalReports(): void {
  const ran = useRef(false);

  useEffect(() => {
    if (ran.current) return;
    ran.current = true;

    const local = readLocal();
    if (local.length === 0) {
      window.localStorage.removeItem(LEGACY_REPORTS_KEY);
      return;
    }

    void (async () => {
      // 1. Read the account copy FIRST: a PUT before this GET would clobber
      //    history another device already lifted.
      const get = await fetch("/api/v1/me/generated-reports", {
        credentials: "include",
      });
      if (!get.ok) return; // keep the local copy; retry on next start

      const body: { data?: { reports?: unknown } } = await get.json();
      const server = Array.isArray(body?.data?.reports)
        ? (body.data.reports as Array<{ id?: unknown }>)
        : [];

      // 2. Union by id; the server copy wins for ids it already has.
      const byId = new Map<string, unknown>();
      for (const r of server) {
        if (typeof r.id === "string") byId.set(r.id, r);
      }
      for (const r of local) {
        const id = (r as { id?: unknown }).id;
        if (typeof id === "string" && !byId.has(id)) byId.set(id, r);
      }

      // 3. Push the union, and only clear locally once the PUT succeeded.
      const put = await fetch("/api/v1/me/generated-reports", {
        method: "PUT",
        credentials: "include",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ reports: [...byId.values()] }),
      });
      if (put.ok) window.localStorage.removeItem(LEGACY_REPORTS_KEY);
    })();
  }, []);
}

1. Read the local key once on app start.
2. Fetch the account copy first; never PUT before that GET settles.
3. Union by id, server copy winning.
4. Clear the local copy only after the PUT succeeds; on any failure leave it in place and retry on the next start.

​

Cross-device behaviour after the lift

• Sign in on a second machine and your saved drafts, your report history, and your pinned favorites are already there.
• The mobile dashboard reads the same account store, so the dialpad favorites on your phone are the same pins as on the web dialpad.
• Clearing browser data no longer erases history; it only drops the local cache the dashboard uses to paint instantly before the network answers.

​

PII: report history is metadata-only

​

Speed-dial favorites: a real table, not a preferences key

​

Extending the pattern in your own tooling

• Key state to the signed-in user, never to the browser alone; where you keep a local cache for instant paint, key it by user id and treat the account copy as authoritative.
• One namespaced key per surface, merged on write, never a whole-record write-back.
• Decide what the payload may contain before you persist it, and strip contact-level data at the boundary the way report history does.
• Read defensively: skip unknown or drifted fields instead of erroring, so older clients survive newer payloads.

​

See also

• Developer console overview — the hub that groups the operator and developer surfaces built on the same API.
• Dashboard home — the landing surface whose per-user widgets read from the account store described here.