crowd-funder-for-time-pwa/src/interfaces/alertSearch.ts

/**
 * alertSearch response item and envelope types.
 *
 * These buckets are new to this app. Item shapes are taken from the endorser-ch
 * SELECT lists for alertSearch, not from similarly named existing report types.
 *
 * Existing types that were considered and not reused:
 * - GenericCredWrapper — claims lack a `claim` body; extra jwt columns differ.
 * - GiveSummaryRecord / OfferSummaryRecord — those use `jwtId` and give/offer
 *   summary fields; alertSearch jwt rows use `id` and jwt table columns.
 * - PlanSummaryAndPreviousClaim — `/plansLastUpdatedBetween` wraps `{ plan,
 *   wrappedClaimBefore }`; alertSearch `trackedPlanUpdates` are plan_claim rows.
 * - PlanSummaryRecord — overlapping plan fields, but the app type is a subset
 *   (missing fulfillsLinkConfirmed, result*, etc.) and required fields differ.
 * - UserProfile — partner nearby rows include `updatedAt` / `rowId` and omit
 *   embedding flags that UserProfile models.
 */

/**
 * Server-issued ULID on a stored JWT/plan record, used as alertSearch afterId /
 * beforeId. Not an authentication JWT and not a delegated notification JWT.
 * Superseded by AlertSearchCursor for "what changed since" queries.
 */
export type AlertSearchCursorUlid = string;

/**
 * Opaque cursor: a position between changes on one server. Responses return
 * `nextAfterCursor` and `nextBeforeCursor`; requests send them back as
 * `afterCursor` (changes after it, oldest first) or `beforeCursor` (changes
 * before it, newest first). Store it as text and never parse or compare it;
 * its format belongs to the server (see endorser-ch
 * CHANGE/PLAN-accurate-cursors.md).
 */
export type AlertSearchCursor = string;

/**
 * JWT row from endorser `jwtsWithDidAfterId` (no claim body).
 * Cursor field: `id`.
 */
export interface AlertSearchClaimRecord {
  id: AlertSearchCursorUlid;
  /** Server change sequence of this row; ascending within a cursor-path list. */
  changeSeq?: number;
  issuedAt: string;
  issuer: string;
  subject?: string;
  claimType?: string;
  handleId?: string;
  fromEntity?: string;
  toEntity?: string;
}

/**
 * JWT row from `jwtsForUserPlanContributions` and
 * `jwtsGiveActionOfferForPlanHandleIds`. `claim` is the jwt table TEXT
 * (canonical JSON string); alertSearch does not JSON.parse it.
 * Cursor field: `id`.
 */
export interface AlertSearchJwtWithClaimRecord extends AlertSearchClaimRecord {
  claim?: string;
}

/**
 * plan_claim row from `plansLastUpdatedBetween` and `plansByLocationAfterId`.
 * Cursor field: `jwtId` (not `id`).
 */
export interface AlertSearchPlanRecord {
  handleId: string;
  jwtId: AlertSearchCursorUlid;
  /** Server change sequence of this row; ascending within a cursor-path list. */
  changeSeq?: number;
  issuerDid?: string;
  agentDid?: string;
  fulfillsLinkConfirmed?: boolean | number;
  fulfillsPlanClaimId?: string;
  fulfillsPlanHandleId?: string;
  name?: string;
  description?: string;
  image?: string;
  endTime?: string;
  startTime?: string;
  locLat?: number;
  locLon?: number;
  resultDescription?: string;
  resultIdentifier?: string;
  url?: string;
}

/**
 * user_profile row from partner `profilesByLocationAfterDate`.
 * Profiles have no JWT `id`; partner paging uses dates decoded from cursor ULIDs.
 */
export interface AlertSearchProfileRecord {
  rowId?: number;
  /** Server change sequence of this row; ascending within a cursor-path list. */
  changeSeq?: number;
  issuerDid: string;
  updatedAt?: string;
  description: string;
  locLat?: number;
  locLon?: number;
  locLat2?: number;
  locLon2?: number;
}

export interface EndorserAlertSearchData {
  claims: AlertSearchClaimRecord[];
  personalPlanContributions: AlertSearchJwtWithClaimRecord[];
  trackedPlanUpdates: AlertSearchPlanRecord[];
  trackedPlanClaims: AlertSearchJwtWithClaimRecord[];
  plansNearby: AlertSearchPlanRecord[];
}

/**
 * A profile or plan close in meaning to the requester's profile, from partner
 * `profilesSimilar` / `plansSimilar` (best first; not paged).
 */
export interface AlertSearchSimilarProfile {
  similarity: number;
  profile: AlertSearchProfileRecord;
}

export interface AlertSearchSimilarPlan {
  similarity: number;
  plan: AlertSearchPlanRecord;
}

export interface PartnerAlertSearchData {
  profilesNearby: AlertSearchProfileRecord[];
  profilesSimilar?: AlertSearchSimilarProfile[];
  plansSimilar?: AlertSearchSimilarPlan[];
}

/**
 * Endorser GET/POST /api/v2/report/alertSearch body.
 * The cursors and `hasMore` are absent from servers that predate cursors.
 * Timeouts may set `userMessage`; the cursor then does not move.
 */
export interface EndorserAlertSearchResponse {
  data: EndorserAlertSearchData;
  userMessage?: string;
  /** Send as `afterCursor` to get what changed after this response. */
  nextAfterCursor?: AlertSearchCursor;
  /** Send as `beforeCursor` to scroll back past this response. */
  nextBeforeCursor?: AlertSearchCursor;
  /**
   * A list was cut at its limit: call again in the same direction, with
   * `afterCursor = nextAfterCursor` or `beforeCursor = nextBeforeCursor`.
   */
  hasMore?: boolean;
}

/**
 * Partner GET/POST /api/partner/alertSearch body.
 */
export interface PartnerAlertSearchResponse {
  data: PartnerAlertSearchData;
  userMessage?: string;
  /** Send as `afterCursor` to get what changed after this response. */
  nextAfterCursor?: AlertSearchCursor;
  /** Send as `beforeCursor` to scroll back past this response. */
  nextBeforeCursor?: AlertSearchCursor;
  /**
   * A list was cut at its limit: call again in the same direction, with
   * `afterCursor = nextAfterCursor` or `beforeCursor = nextBeforeCursor`.
   */
  hasMore?: boolean;
}

/**
 * Union of the six alertSearch buckets for a future combined daily run.
 * Not returned by a single server endpoint today.
 */
export interface CombinedAlertSearchData
  extends EndorserAlertSearchData,
    PartnerAlertSearchData {}