// Types for create-card.js — WRITTEN rather than `@ts-expect-error`'d, on retry.d.ts's criterion:
// this is our module and getting it wrong is customer-facing.
//
// 🔴 What a declaration buys HERE specifically is that the CONTEXT is the whole card context and
// not a loose bag. Under `any`, `createCard({ client }, …)` compiles — and it would reach the card
// store with no `accountId`, i.e. with no tenant, which is the one mistake this feature cannot
// survive: a handle reserved against nobody, or a starter card written over somebody's live one.
// The runtime still fails closed on a missing account; this is what makes the mistake unwritable.

/** The card context every card tool is handed — hosted/src/index.ts's `cardCtx()`. */
export interface CardContext {
  /** RSP's registry client (src/rsp-registry-client.js). */
  registry: {
    accountQuota(accountId: string): Promise<{
      owned: number;
      quota: number | null;
      cards: { owned: number; quota: number | null } | null;
    }>;
    registerCard(p: {
      handle: string;
      accountId: string;
      createdBy: string;
      vanityHost?: string | null;
    }): Promise<{ created: boolean; handle: string; quota: { used: number; limit: number } | null }>;
    releaseCard(p: { handle: string; accountId: string; createdBy: string }): Promise<{ released: boolean }>;
  };
  /** 🔴 The VERIFIED tenant. Required — a card reserved against nobody belongs to nobody. */
  accountId: string;
  /** The cardtile client (src/card-client.js). Only the two operations this module uses. */
  client: {
    summaries(handles: string[]): Promise<{ cards: Array<{ handle: string }> }>;
    save(handle: string, body: { markdown: string; message?: string }): Promise<{ version?: string }>;
  };
}

export interface CreateCardArgs {
  /** The public address. 1–39 chars, lowercase alnum + hyphens. PERMANENT — never reassigned. */
  handle: string;
  /** The display name on the card. */
  title: string;
  tagline?: string;
  /** One `[Name](url)` per line. */
  social?: string;
}

export interface CreateCardResult {
  handle: string;
  live_url: string;
  version?: string;
  /** 🔴 About the CARD: there is now a card at this address. Always true on a returned result. */
  created: true;
  /** Present only when the ledger row PRE-EXISTED — a retry after an earlier failed store write. */
  note?: string;
  quota?: { used: number; limit: number };
  message: string;
  next: string;
}

/** The starter card's markdown — exported so a test can read the shape without a network. */
export function starterCardMarkdown(p: {
  handle: string;
  title: string;
  tagline?: string;
  social?: string;
}): string;

/**
 * Reserve the handle in RSP's ledger, then write the starter card. On any failure after the
 * reservation, the row is given back (see the .js header) — so this either returns a card that
 * exists in both stores, or throws.
 *
 * @param deps.newNonce  the rollback nonce, injectable so a test can pin it.
 */
export function createCard(
  ctx: CardContext,
  args: CreateCardArgs,
  deps?: { newNonce?: () => string },
): Promise<CreateCardResult>;