/**
 * Hand-authored declarations for the "." export of ardegazu-social-kit —
 * the compiled dist/index.js (ClojureScript). Mirrors the v1 TypeScript
 * API surface exactly; wire and storage shapes are unchanged.
 */
import type { Bytes, Identity } from "ardegazu-id-kit";
import type { Wrap, XKeyPair } from "ardegazu-id-kit/xkey";

export type { SocialTextKey, SocialVars, SocialT } from "./text.js";
export { enText, mkT } from "./text.js";
import type { SocialT } from "./text.js";

// ---- consts ----------------------------------------------------------------

export declare const SOCIAL_SALT: string;
export declare const SOC_BEACON_MS: number;
export declare const SOC_STALE_MS: number;
export declare const ENV_DEFAULT_TTL_MS: number;
export declare const INVITE_TTL_MS: number;
export declare const SEEN_ENV_CAP: number;
export declare const BLOCKED_CAP: number;
export declare const PENDING_UI_CAP: number;
export declare const RECEIPTS_CAP: number;
export declare const AP2P_DESCRIPTOR_URL: string;
export declare const MAILBOX_URL_FALLBACK: string;
export declare const MAILBOX_CREDS_URL_FALLBACK: string;

// ---- canon -----------------------------------------------------------------

/** Canonical JSON: sorted keys, no whitespace; throws on non-JSON-safe values. */
export declare function canon(value: unknown): string;
export declare function sha256(data: Bytes): Promise<Bytes>;
export declare function sha256B64url(s: string): Promise<string>;
/** HKDF-SHA256 → base64url string id (the suite's standard derivation shape). */
export declare function hkdfId(ikm: Bytes, salt: string, info: string): Promise<string>;
/** HKDF-SHA256 → AES-GCM key. */
export declare function hkdfAesKey(ikm: Bytes, salt: string, info: string): Promise<CryptoKey>;

// ---- mailbox ---------------------------------------------------------------

export interface MailboxEndpoints {
  baseUrl: string;
  credsUrl: string;
  maxMessageKb: number;
}

export declare function mailboxEndpoints(descriptorUrl?: string): Promise<MailboxEndpoints>;

export declare class MailboxAuth {
  constructor(credsUrl: string, roomId: string);
  get(): Promise<string>;
  /** Drop the cached token (server said 401/403) so the next get() re-mints. */
  invalidate(): void;
}

export type DepositResult =
  | { ok: true; deduped: boolean; seq: string }
  | { ok: false; kind: "too_large" | "auth" | "backpressure" | "net" };

export interface ReplayMessage {
  seq: string;
  id: string;
  ts: number;
  payload: string; // base64
}

export interface ReplayPage {
  messages: ReplayMessage[];
  hasMore: boolean;
  oldestSeq: string | null;
  latestSeq: string | null;
}

export type ReplayResult = { ok: true; page: ReplayPage } | { ok: false; kind: "auth" | "backpressure" | "net" };

export declare class MailboxClient {
  constructor(baseUrl: string, roomId: string, auth: MailboxAuth);
  deposit(payload: Uint8Array): Promise<DepositResult>;
  replay(after: string | null, limit: number): Promise<ReplayResult>;
}

/** Convenience: a client for one client-derived room id. */
export declare function mailboxFor(roomId: string): Promise<MailboxClient>;

// ---- envelope --------------------------------------------------------------

export type EnvType = "freq" | "facc" | "inv" | "fsync" | "bye";

export interface EnvFrom {
  pub: string; // Ed25519 identity
  x: string; // suite X25519 pub
  xs: string; // X-cert (Ed25519 sig binding x to pub under SUITE_SALT)
  name: string;
}

export interface EnvelopeInner {
  t: EnvType;
  id: string; // 16 random bytes b64url — the dedup key
  from: EnvFrom;
  ts: number;
  exp: number;
  body: Record<string, unknown>;
  sig: string;
}

/** Everything the sender side needs; built once per session. */
export interface SelfCrypto {
  identity: Identity;
  x: XKeyPair;
  xCert: string;
  name: string;
}

/** Build a sealed envelope addressed to (toIdPub, toXPub) in context `ctx`. */
export declare function buildEnvelope(
  self: SelfCrypto,
  ctx: string,
  toIdPub: string,
  toXPub: string,
  t: EnvType,
  body: Record<string, unknown>,
  ttlMs?: number,
): Promise<{ bytes: Bytes; id: string; outer: { v: 1; w: Wrap } }>;

/** Open + fully verify an envelope addressed to us in context `ctx`; null on ANY failure. */
export declare function openEnvelope(myX: XKeyPair, ctx: string, bytes: Bytes): Promise<EnvelopeInner | null>;

/** Persisted dedup ring for envelope ids (drop-oldest, try/catch storage). */
export declare class SeenRing {
  constructor(storageKey: string, cap?: number);
  readonly cap: number;
  has(id: string): boolean;
  add(id: string): void;
}

// ---- pair ------------------------------------------------------------------

export interface Channel {
  /** Internal channel id; also the wrap ctx prefix for envelopes on it. */
  id: string;
  topic: string;
  mailboxRoomId: string;
  /** Envelope wrap context for this channel. */
  ctx: string;
  /** sender idPub → keyed wire alias (only members can map back). */
  tagOf(idPub: string): Promise<string>;
  seal(myPub: string, payload: unknown): Promise<string>;
  /** Try every member's key by tag; null = not from this channel / tampered. */
  open(wire: string, memberPubs: string[]): Promise<{ from: string; payload: unknown } | null>;
}

/** The channel I share with one friend (order-independent). */
export declare function pairChannel(myX: XKeyPair, myPub: string, friendPub: string, friendXPub: string): Promise<Channel>;
/** The channel all devices of MY identity share (from the seed). */
export declare function selfChannel(seedB64url: string): Promise<Channel>;
/** The identity-addressed inbox room id (publicly derivable from idPub). */
export declare function inboxRoomId(idPub: string): Promise<string>;
/** Envelope wrap context: recipient-bound, transport-agnostic. */
export declare function envCtx(toIdPub: string): string;

// ---- friends ---------------------------------------------------------------

export type FriendState = "friend" | "out" | "in";

export interface Friend {
  pub: string;
  x: string;
  xs: string;
  /** My label for them (petname beats their self-claimed name). */
  pet: string;
  /** Their latest self-claimed name (hint only). */
  name: string;
  state: FriendState;
  addedTs: number;
  petTs: number;
  lastSeenTs: number;
  lastApp: string;
  /** Incoming request note, when they sent one. */
  note?: string;
}

export interface BlockedEntry {
  pub: string;
  ts: number;
}

export interface SocBlob {
  v: 1;
  friends: Friend[];
  blocked: BlockedEntry[];
  ts: number;
}

/** Validate one untrusted friend record into a fresh object, or null. */
export declare function sanitizeFriend(e: unknown): Friend | null;

export declare class FriendStore {
  constructor(ns: string);
  /** Fires after every mutation (UI re-render + bridge/self-channel push). */
  onChange: () => void;
  list(): Friend[];
  blocked(): BlockedEntry[];
  get(pub: string): Friend | null;
  friends(): Friend[];
  isBlocked(pub: string): boolean;
  /** Insert or update; existing state only upgrades (in/out → friend). */
  upsert(f: Friend): void;
  setPet(pub: string, pet: string): void;
  seen(pub: string, app: string): void;
  markFriend(pub: string): void;
  /** Remove + tombstone: envelopes from this pub are dropped from now on. */
  block(pub: string): void;
  /** Just forget (no tombstone): a later request shows up again. */
  forget(pub: string): void;
  /** Display name: petname beats their claim beats a fingerprint stub. */
  labelOf(f: Friend): string;
  socBlob(): SocBlob;
  /** Fold a remote blob (another device of OUR identity). Returns records changed. */
  merge(remote: unknown): number;
}

export interface FriendLink {
  pub: string;
  x: string;
  xs: string;
  name: string;
}

export declare function buildFriendLink(base: string, me: FriendLink): string;
/** Parse + verify a friend link fragment; null = malformed or forged cert. */
export declare function parseFriendLink(fragment: string): Promise<FriendLink | null>;

export interface FriendEvents {
  request(f: Friend): void;
  accepted(f: Friend): void;
  synced(changed: number): void;
}

/** Fold one verified envelope into the store; true when it changed anything. */
export declare function applyFriendEnvelope(
  store: FriendStore,
  env: EnvelopeInner,
  ev?: Partial<FriendEvents>,
  selfPub?: string,
): boolean;

// ---- selfsync --------------------------------------------------------------

/** One device's profile snapshot; `ts` is the edit time newest-wins folds on. */
export interface ProfileSyncBlob {
  name: string;
  hue: number | null;
  glyph: string | null;
  lang: string | null;
  ts: number;
}

/** Shape-check + clamp one untrusted profile section into a fresh object, or null. */
export declare function sanitizeProfileSync(p: unknown): ProfileSyncBlob | null;
/** Fold two devices' profile snapshots (newest wins wholesale; backfill otherwise). */
export declare function foldProfileSync(local: ProfileSyncBlob, remote: ProfileSyncBlob): ProfileSyncBlob;

/** One app's section of the suite identity record's `apps` field. */
export interface AppsSyncEntry {
  /** The app's own blob — opaque to the kit, but must be JSON-serializable
   *  and at most 16384 UTF-16 CODE UNITS of `JSON.stringify(state)`
   *  (id-kit's MAX_APP_STATE_BYTES, in id-kit's unit — never UTF-8 bytes,
   *  which for ro/hu text is roughly twice the count). */
  state: unknown;
  /** Write time; the per-key fold turns on it. Clamped to NOW — a section is
   *  never emitted with a timestamp from the future. */
  ts: number;
}

/** appKey -> that app's section. Keys match /^[a-z0-9-]{1,32}$/.
 *
 *  Key order is DETERMINISTIC, not lexicographic: entries are inserted in
 *  sorted order, but JS canonical property order hoists all-digit keys (which
 *  the charset permits) numerically ahead of the rest — `"2"` before `"10"`
 *  before `"board"`. The same key set always serializes to the same bytes,
 *  whichever device produced it.
 *
 *  No entry-count cap and no eviction: this is the user's own data. Total size
 *  is capped at 98304 UTF-16 code units of the serialized map (id-kit's
 *  MAX_APPS_BYTES); an entry that would exceed it is skipped in key order and
 *  smaller ones after it are still kept. */
export type AppsSyncMap = Record<string, AppsSyncEntry>;

/** Shape-check + clamp one untrusted apps section into a fresh object, or null
 *  when nothing survives (so the section is omitted rather than sent empty).
 *  Never throws: an entry whose property read throws costs that entry only. */
export declare function sanitizeAppsSync(m: unknown): AppsSyncMap | null;
/** Fold two devices' apps sections PER KEY, over the union of both key sets:
 *  strictly newer `ts` wins that key wholesale, equal `ts` with differing
 *  content is broken by the greater canonical serialization (role-independent,
 *  so both devices converge), and a key only one side has is adopted as it
 *  stands. Commutative and idempotent; no key can drag a sibling.
 *
 *  Never throws, and never returns a poisoned object: keys outside the app-key
 *  charset are dropped, so a `__proto__` own key (what `JSON.parse` of wire
 *  text produces) cannot reach the result's prototype. Inputs are expected to
 *  have come through `sanitizeAppsSync`; for input that did not, an equal-`ts`
 *  tiebreak over a value `canon()` refuses degrades to keeping `local` instead
 *  of throwing — that one key then does not converge. */
export declare function foldAppsSync(local: AppsSyncMap, remote: AppsSyncMap): AppsSyncMap;

// ---- presence (the social agent) -------------------------------------------

/** The pubsub surface both libp2p generations expose (services.pubsub). */
export interface PubsubLike {
  subscribe(topic: string): void;
  unsubscribe(topic: string): void;
  publish(topic: string, data: Uint8Array): Promise<unknown>;
  addEventListener(
    type: "message",
    cb: (evt: { detail: { topic: string; data: Uint8Array } }) => void,
  ): void;
}

export interface PresenceInfo {
  name: string;
  app: string;
  join: string | null;
  ts: number;
  /** Brain/model versions this peer is currently playing (game id -> version),
   *  as announced on its beacons. Absent when the peer sends none (every
   *  browser client) — bots are what fill it. Clamped on receive: at most 8
   *  entries, keys /^[a-z0-9][a-z0-9-]{0,23}$/, values /^[A-Za-z0-9@._-]{1,32}$/.
   *  Still UNTRUSTED NETWORK INPUT: render via textContent, never innerHTML. */
  brains?: Record<string, string>;
}

export interface InviteMsg {
  id: string;
  from: Friend;
  app: string;
  url: string;
  label: string;
  /** Message code carried instead of prose — receivers render it in their own
   *  language. Absent from envelopes sent by older kits (label is the fallback). */
  msg?: { k: string };
  ts: number;
}

export interface SocialAgentOpts {
  /** Storage namespace (cursors, dedup ring). */
  ns: string;
  /** Which app this tab is (e.g. "game5.ardegazu.ro"). */
  app: string;
  identity: Identity;
  /** The 43-char identity seed (self-channel derivation). */
  seed: string;
  /** My current display name (announced in beacons + envelopes). */
  myName: () => string;
  store: FriendStore;
  /** The app's libp2p pubsub; null = mailbox-only (no live presence). */
  pubsub: PubsubLike | null;
  /** Room link to share with friends ("friends can join me") — explicit opt-in. */
  joinLink?: () => string | null;
  /** Brain/model versions I am currently playing (game id -> version), read at
   *  every beacon so the value tracks itself. Clamped before it hits the wire
   *  (at most 8 entries, keys /^[a-z0-9][a-z0-9-]{0,23}$/, values
   *  /^[A-Za-z0-9@._-]{1,32}$/); omitted entirely when unset or empty. */
  brains?: () => Record<string, string> | null;
  /** Mirror my profile across my devices (rides the self fsync; optional). */
  profileSync?: { get(): ProfileSyncBlob | null; apply(p: ProfileSyncBlob): void };
  /** Mirror one app-scoped state blob across my devices (ns-gated on receive). */
  appState?: { get(): unknown | null; apply(state: unknown): void };
  /** Mirror the identity record's per-app map across my devices (rides the
   *  self fsync; optional). Distinct from `appState`: that is one blob for
   *  THIS app, gated on `ns`; this is every app's section, folded per key. */
  appsSync?: { get(): AppsSyncMap | null; apply(m: AppsSyncMap): void };
  events: {
    presence?(pub: string, info: PresenceInfo | null): void;
    invite?(inv: InviteMsg): void;
    request?(f: Friend): void;
    accepted?(f: Friend): void;
    synced?(changed: number): void;
  };
}

export declare class SocialAgent {
  constructor(opts: SocialAgentOpts);
  get myPub(): string;
  presenceOf(pub: string): PresenceInfo | null;
  start(): Promise<void>;
  stop(): void;
  /** Join (or re-join) the channel for one friend record. */
  joinFriendChannel(f: Friend): Promise<void>;
  leaveFriendChannel(pub: string): void;
  /** Send a friend request to a parsed link target. */
  sendFriendRequest(to: { pub: string; x: string; xs: string; name: string }, note?: string): Promise<boolean>;
  /** Accept a pending request. */
  acceptRequest(pub: string): Promise<boolean>;
  /** Invite friends into a room: live when reachable, pair drop otherwise. */
  sendInvite(pubs: string[], app: string, url: string, label: string, msg?: { k: string }): Promise<number>;
  /** Debounced self-sync for app-driven changes (profile edits, app state). */
  syncNow(): void;
}

// ---- invites ---------------------------------------------------------------

export interface AppDef {
  host: string;
  name: string;
  kind: "chat" | "board" | "game";
}

/** The invitable suite (hub excluded — you're already there). */
export declare const SUITE_APPS: readonly AppDef[];

/** Mint a fresh room on an app (43-char b64url fragment secret). */
export declare function mintRoomUrl(host: string): string;

// ---- notify ----------------------------------------------------------------

export interface InviteToastOpts {
  /** Display name for the inviter (petname beats claim). */
  label: string;
  /** Called on accept; default navigates to inv.url. */
  onAccept?: (inv: InviteMsg) => void;
  /** App translator for the toast's strings; EN built-ins otherwise. */
  t?: SocialT;
  timeoutMs?: number;
}

export declare function inviteToast(inv: InviteMsg, opts: InviteToastOpts): void;

// ---- receipts --------------------------------------------------------------

export interface ReceiptScore {
  p: string; // player idPub
  nm: string; // self-claimed name at match time
  s: number; // score
}

export interface Receipt {
  v: 1;
  g: string; // game id (its APP_SALT)
  m: string; // mode, game-defined
  r: string; // room hash (sha256("lbroom|"+roomId), truncated) — not the room
  ts: number;
  n: number; // players present
  sc: ReceiptScore[];
  sig: { p: string; s: string }[];
}

export type ReceiptBase = Omit<Receipt, "sig">;

export declare const MIN_SIGNERS: number;

export declare function roomHash(roomId: string): Promise<string>;
export declare function receiptHash(rec: Receipt | ReceiptBase): Promise<string>;
export declare function signReceipt(identity: Identity, base: ReceiptBase): Promise<{ p: string; s: string }>;

export interface VerifyOpts {
  /** Per-game sanity cap on a single score. */
  maxScore?: number;
  /** Reject receipts with ts outside [now - maxAgeMs, now + 5min]. */
  maxAgeMs?: number;
}

/** Full verification; null = reject. Returns the receipt's dedup hash. */
export declare function verifyReceipt(raw: unknown, opts?: VerifyOpts): Promise<{ rec: Receipt; hash: string } | null>;

/** ISO week ("2026-W35") of a timestamp — the weekly leaderboard's bucket. */
export declare function isoWeek(ts: number): string;
export declare function lbRoomId(g: string, week: string): Promise<string>;
export declare function lbTopic(g: string): Promise<string>;

/** Deposit a receipt into this week's public drop (plaintext — signed, public data). */
export declare function depositReceipt(rec: Receipt): Promise<boolean>;
/** Replay + verify a week's drop. Best-effort, capped pages. */
export declare function fetchWeekly(g: string, week: string, opts?: VerifyOpts): Promise<Receipt[]>;

export declare class ReceiptSet {
  constructor(ns: string);
  all(): Receipt[];
  /** Add a VERIFIED receipt (call verifyReceipt first). */
  add(rec: Receipt): Promise<boolean>;
}

export interface LbRow {
  pub: string;
  name: string;
  best: number;
  total: number;
  plays: number;
}

/** Fold receipts into a top list (per player: best single score, totals). */
export declare function aggregate(recs: Receipt[]): LbRow[];

// ---- gamelb ----------------------------------------------------------------

export interface LbNetLike {
  myId: string;
  broadcast(frame: unknown): void;
  send(to: string, frame: unknown): void;
  identityOf(id: string): { pub: string } | null;
}

export interface GameLbOpts {
  /** The game's id on the board — its APP_SALT. */
  g: string;
  /** Room id (hashed before it ever leaves the room). */
  roomId: string;
  ns: string;
  identity: Identity | null;
  net: LbNetLike;
  /** My current score as the game believes it (null = don't co-sign). */
  myScore: () => number | null;
  /** Optional mode label. */
  mode?: string;
  /** A verified receipt landed (own match or replayed) — update UI if any. */
  onReceipt?: (rec: Receipt) => void;
}

export declare class GameLb {
  constructor(opts: GameLbOpts);
  readonly receipts: ReceiptSet;
  /** HOST: a match just ended — ask the players present to co-sign. */
  hostMatchEnd(scores: [string, string, number][]): Promise<void>;
  /** Route a wire frame; true = it was a leaderboard frame (consumed). */
  onFrame(from: string, frame: unknown): boolean;
}

// ---- lbgossip --------------------------------------------------------------

export interface LbGossipOpts {
  pubsub: PubsubLike;
  /** The shared carried set (create ONE per page and pass it here). */
  receipts: ReceiptSet;
  /** Game ids (their APP_SALTs) to converge. */
  games: string[];
  verify?: VerifyOpts;
  /** A verified foreign receipt was folded in. */
  onNew?: (rec: Receipt) => void;
}

export declare function startLbGossip(opts: LbGossipOpts): Promise<{ stop(): void }>;

// ---- app-boot --------------------------------------------------------------

export interface AttachSocialOpts {
  /** Storage namespace (the app's NS). */
  ns: string;
  /** This app's host, e.g. "game5.ardegazu.ro". */
  app: string;
  identity: Identity;
  seed: string;
  myName: () => string;
  pubsub: PubsubLike | null;
  /** The suite record's soc blob (bridge), if any — seeds the friend list. */
  soc?: unknown;
  /** Provide the current room link when the user flips "friends can join". */
  roomLink?: () => string;
  /** Skip the chips (apps without a shareable room concept). */
  noJoinToggle?: boolean;
  /** Brain/model versions this peer is playing (game id -> version), read at
   *  every beacon; same clamp as SocialAgentOpts.brains. Bots fill it. */
  brains?: () => Record<string, string> | null;
  /** Mirror my profile across my devices (rides the self fsync; optional). */
  profileSync?: { get(): ProfileSyncBlob | null; apply(p: ProfileSyncBlob): void };
  /** Mirror one app-scoped state blob across my devices (ns-gated on receive). */
  appState?: { get(): unknown | null; apply(state: unknown): void };
  /** Mirror the identity record's per-app map across my devices; passed
   *  straight through to SocialAgentOpts.appsSync. */
  appsSync?: { get(): AppsSyncMap | null; apply(m: AppsSyncMap): void };
  /** App translator for the kit's chip/sheet/toast strings; EN built-ins otherwise. */
  t?: SocialT;
}

/** One-call social attachment for suite apps; null when anything fails (never breaks the app). */
export declare function attachSocial(opts: AttachSocialOpts): Promise<SocialAgent | null>;