@mohasinac/appkit 2.3.2 → 2.4.1

package/dist/features/scams/repository/scammer.repository.js

@@ -0,0 +1,160 @@
+import { DatabaseError } from "../../../errors";
+import { BaseRepository, prepareForFirestore, } from "../../../providers/db-firebase";
+import { increment } from "../../../contracts/field-ops";
+import { SCAMMER_COLLECTION, SCAMMER_FIELDS, SCAMMER_INCIDENTS_SUBCOLLECTION, SCAMMER_COMMENTS_SUBCOLLECTION, DEFAULT_SCAMMER_DATA, } from "../schemas/firestore";
+class ScammerRepository extends BaseRepository {
+    constructor() {
+        super(SCAMMER_COLLECTION);
+    }
+    async listVerified(model) {
+        const baseQuery = this.getCollection().where(SCAMMER_FIELDS.STATUS, "==", "verified");
+        return this.sieveQuery(model, ScammerRepository.SIEVE_FIELDS, {
+            baseQuery,
+            defaultPageSize: 20,
+            maxPageSize: 50,
+        });
+    }
+    async listAll(model) {
+        return this.sieveQuery(model, ScammerRepository.SIEVE_FIELDS, {
+            defaultPageSize: 50,
+            maxPageSize: 200,
+        });
+    }
+    async findBySeoSlug(seoSlug) {
+        try {
+            const snap = await this.getCollection()
+                .where(SCAMMER_FIELDS.SEO_SLUG, "==", seoSlug)
+                .limit(1)
+                .get();
+            if (snap.empty)
+                return null;
+            return this.mapDoc(snap.docs[0]);
+        }
+        catch (error) {
+            throw new DatabaseError(`Failed to find scammer by seoSlug: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async create(input) {
+        try {
+            const now = new Date();
+            const id = input.displayNames[0]
+                ? `scammer-${input.displayNames[0].toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").slice(0, 40)}-${Date.now().toString(36)}`
+                : `scammer-${Date.now().toString(36)}`;
+            const data = prepareForFirestore({
+                ...DEFAULT_SCAMMER_DATA,
+                ...input,
+                id,
+                seoSlug: id,
+                relatedScammerIds: [],
+                mergedFromIds: [],
+                tags: [],
+                views: 0,
+                incidentCount: 0,
+                commentCount: 0,
+                contestCount: 0,
+                isContested: false,
+                status: "pending_review",
+                createdAt: now,
+                updatedAt: now,
+            });
+            await this.getCollection().doc(id).set(data);
+            return { ...data, id };
+        }
+        catch (error) {
+            throw new DatabaseError(`Failed to create scammer profile: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async adminUpdate(id, input) {
+        try {
+            const data = prepareForFirestore({ ...input, updatedAt: new Date() });
+            await this.getCollection().doc(id).update(data);
+        }
+        catch (error) {
+            throw new DatabaseError(`Failed to update scammer profile: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async incrementViews(id) {
+        try {
+            await this.getCollection()
+                .doc(id)
+                .update({ [SCAMMER_FIELDS.VIEWS]: increment(1) });
+        }
+        catch {
+            // Fire-and-forget by design.
+        }
+    }
+    /**
+     * Search for profiles whose phones, upiIds, emails, or displayNames arrays
+     * contain any of the given values. Used for duplicate detection on new reports.
+     */
+    async findByContactField(field, value) {
+        try {
+            const snap = await this.getCollection()
+                .where(field, "array-contains", value)
+                .limit(5)
+                .get();
+            return snap.docs.map((d) => this.mapDoc(d));
+        }
+        catch (error) {
+            throw new DatabaseError(`Failed to search scammer by ${field}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async listPublicIncidents(scammerId) {
+        try {
+            const snap = await this.db
+                .collection(SCAMMER_COLLECTION)
+                .doc(scammerId)
+                .collection(SCAMMER_INCIDENTS_SUBCOLLECTION)
+                .where("status", "==", "verified")
+                .orderBy("createdAt", "desc")
+                .limit(20)
+                .get();
+            return snap.docs.map((d) => this.mapDoc(d));
+        }
+        catch {
+            return [];
+        }
+    }
+    async listPublicComments(scammerId) {
+        try {
+            const snap = await this.db
+                .collection(SCAMMER_COLLECTION)
+                .doc(scammerId)
+                .collection(SCAMMER_COMMENTS_SUBCOLLECTION)
+                .where("isHidden", "==", false)
+                .orderBy("createdAt", "desc")
+                .limit(30)
+                .get();
+            return snap.docs.map((d) => this.mapDoc(d));
+        }
+        catch {
+            return [];
+        }
+    }
+    async findManyById(ids) {
+        if (!ids.length)
+            return [];
+        try {
+            const results = await Promise.all(ids.slice(0, 5).map((id) => this.findById(id).catch(() => null)));
+            return results.filter((d) => d !== null && d.status === "verified");
+        }
+        catch {
+            return [];
+        }
+    }
+}
+ScammerRepository.SIEVE_FIELDS = {
+    id: { canFilter: true, canSort: false },
+    status: { canFilter: true, canSort: true },
+    scamType: { canFilter: true, canSort: true },
+    scamPlatform: { canFilter: true, canSort: true },
+    reportedBy: { canFilter: true, canSort: false },
+    verifiedBy: { canFilter: true, canSort: false },
+    isContested: { canFilter: true, canSort: false },
+    views: { canFilter: false, canSort: true },
+    incidentCount: { canFilter: false, canSort: true },
+    createdAt: { canFilter: true, canSort: true },
+    updatedAt: { canFilter: false, canSort: true },
+};
+const scammerRepository = new ScammerRepository();
+export { ScammerRepository, scammerRepository };

package/dist/features/scams/schemas/firestore.d.ts

@@ -0,0 +1,362 @@
+/**
+ * Scam Registry Firestore Document Types & Constants
+ *
+ * Data model:
+ *   scammerProfiles/{id}                  — canonical scammer identity (one per person)
+ *   scammerProfiles/{id}/incidents/{id}   — individual victim reports linked to this profile
+ *   scammerProfiles/{id}/comments/{id}    — public discussion; accused can post here
+ *   scammerProfiles/{id}/contests/{id}    — dispute submissions (accused or any user)
+ *
+ * SEO design intent: phones, UPI IDs, and emails are stored as plaintext and
+ * rendered as HTML text nodes so search engines index them. When a victim googles
+ * the number/UPI they received, this page must surface.
+ *
+ * Submission rules (enforced server-side):
+ *  - Requires authentication (no guest submissions)
+ *  - Requires scamAwarenessAcknowledgedAt on UserDocument
+ *  - No submission if user has report_scammers soft ban
+ *  - Max 5 pending submissions per user (prevents spam flooding)
+ *  - All submissions start as "pending_review" — admin must verify before public display
+ *
+ * Suggestion matching (duplicate detection):
+ *  - On new report submission, API queries existing profiles for overlapping
+ *    phones[], upiIds[], emails[], displayNames[]
+ *  - If matches found → suggest linking to existing profile (new incident) instead of new profile
+ *  - SCAMMER_MATCH_FIELDS lists the Firestore array-contains fields used for this query
+ */
+import type { ScamType } from "../constants/scam-types";
+export declare const ScammerStatusValues: {
+    readonly PENDING_REVIEW: "pending_review";
+    readonly VERIFIED: "verified";
+    readonly REJECTED: "rejected";
+    readonly REMOVED: "removed";
+};
+export type ScammerStatus = (typeof ScammerStatusValues)[keyof typeof ScammerStatusValues];
+export declare const ScamPlatformValues: {
+    readonly WHATSAPP: "whatsapp";
+    readonly INSTAGRAM: "instagram";
+    readonly FACEBOOK: "facebook";
+    readonly TELEGRAM: "telegram";
+    readonly TWITTER: "twitter";
+    readonly OLX: "olx";
+    readonly FACEBOOK_MARKETPLACE: "facebook_marketplace";
+    readonly LETITRIP: "letitrip";
+    readonly IN_PERSON: "in_person";
+    readonly PHONE_CALL: "phone_call";
+    readonly OTHER: "other";
+};
+export type ScamPlatform = (typeof ScamPlatformValues)[keyof typeof ScamPlatformValues];
+export declare const SocialPlatformValues: {
+    readonly INSTAGRAM: "instagram";
+    readonly FACEBOOK: "facebook";
+    readonly TWITTER: "twitter";
+    readonly YOUTUBE: "youtube";
+    readonly TELEGRAM: "telegram";
+    readonly WHATSAPP: "whatsapp";
+    readonly LINKEDIN: "linkedin";
+    readonly OLX: "olx";
+    readonly OTHER: "other";
+};
+export type SocialPlatform = (typeof SocialPlatformValues)[keyof typeof SocialPlatformValues];
+export declare const ContestTypeValues: {
+    /** The named person claims they never scammed anyone. */
+    readonly ACCUSED_CONTESTING: "accused_contesting";
+    /** Any user flags the entire report as fabricated. */
+    readonly FALSE_REPORT: "false_report";
+    /** A detail is wrong (wrong phone, wrong name) but the scam is real. */
+    readonly INACCURATE_DETAILS: "inaccurate_details";
+    /** The name/alias matches but it's a different person entirely. */
+    readonly IDENTITY_MISTAKEN: "identity_mistaken";
+};
+export type ContestType = (typeof ContestTypeValues)[keyof typeof ContestTypeValues];
+export declare const ContestStatusValues: {
+    readonly PENDING: "pending";
+    /** Contest accepted — profile edited or removed. */
+    readonly UPHELD: "upheld";
+    /** Contest rejected — report stands as verified. */
+    readonly DISMISSED: "dismissed";
+};
+export type ContestStatus = (typeof ContestStatusValues)[keyof typeof ContestStatusValues];
+export interface ScammerSocialMedia {
+    platform: SocialPlatform;
+    /** Raw handle without @ prefix — stored as plaintext for SEO indexing. */
+    handle: string;
+    url?: string;
+}
+export interface ScammerDocument {
+    id: string;
+    /** URL-safe slug — used in /scams/[slug]. Same as id. */
+    seoSlug: string;
+    /**
+     * Display names / aliases used by the scammer.
+     * Stored as plaintext array — all are indexed for suggestion matching.
+     */
+    displayNames: string[];
+    /**
+     * Phone numbers in any format. Stored plaintext for SEO.
+     * Deduplication (trim, strip spaces/dashes) done server-side on write.
+     */
+    phones: string[];
+    /**
+     * UPI IDs (e.g. 9876543210@paytm). Stored plaintext.
+     * Victims often google UPI IDs before paying — critical for SEO.
+     */
+    upiIds: string[];
+    /** Email addresses used by the scammer. Stored plaintext for SEO. */
+    emails: string[];
+    /** Social media profiles where the scammer operated. */
+    socialMedia: ScammerSocialMedia[];
+    /** Primary scam type for this profile (most common across incidents). */
+    scamType: ScamType;
+    /** Platform where the initial/primary scam interaction occurred. */
+    scamPlatform: ScamPlatform;
+    /** Reporter's narrative for the first/primary incident. */
+    description: string;
+    /** Amount lost in INR paise (0 if none). Optional. */
+    amountLost?: number;
+    /** Item involved in the scam (e.g. "Charizard PSA 9"). Optional. */
+    itemInvolved?: string;
+    /**
+     * Evidence URLs for the primary incident.
+     * Must be /media/ proxy URLs — never raw Firebase Storage URLs.
+     */
+    evidence: string[];
+    /** UID of the user who first reported this scammer. */
+    reportedBy: string;
+    /**
+     * If true, reporter's identity is hidden on the public page.
+     * Admin records keep the uid; public page shows "Anonymous".
+     */
+    reportedByAnon: boolean;
+    status: ScammerStatus;
+    /** UID of admin/employee who verified or rejected. */
+    verifiedBy?: string;
+    verifiedAt?: Date;
+    /** Internal note from the verifier — never shown publicly. */
+    verificationNote?: string;
+    /**
+     * Cross-links to other profiles that are the same person under different aliases.
+     * Used for "Also reported as:" links and merge context.
+     */
+    relatedScammerIds: string[];
+    /**
+     * IDs of profiles that were merged INTO this one.
+     * Old profile pages redirect here; search results de-dup on these.
+     */
+    mergedFromIds?: string[];
+    /** Admin/system tags for internal filtering (e.g. "high_value", "repeat_offender"). */
+    tags: string[];
+    /** Page view counter — incremented server-side. */
+    views: number;
+    /** Total verified + pending incident reports linked to this profile. */
+    incidentCount: number;
+    /** Total visible (non-hidden) comments on this profile. */
+    commentCount: number;
+    /** Total open (pending) contest submissions. */
+    contestCount: number;
+    /**
+     * True when ≥1 pending contest exists — surfaces in admin moderation queue.
+     * Reset to false when all contests are reviewed.
+     */
+    isContested?: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * One victim's report linked to an existing scammer profile.
+ *
+ * When a new submission matches an existing verified profile's phones/UPIs/emails,
+ * it is stored here instead of creating a duplicate top-level profile.
+ * The public detail page shows these in a table ("Other victims who reported this person").
+ */
+export interface ScammerIncidentDocument {
+    /** Firestore auto-ID — incidents never get semantic slugs. */
+    id: string;
+    /** Parent ScammerDocument id. */
+    scammerId: string;
+    reportedBy: string;
+    reportedByAnon: boolean;
+    scamType: ScamType;
+    scamPlatform: ScamPlatform;
+    description: string;
+    amountLost?: number;
+    itemInvolved?: string;
+    /** Evidence for this specific incident. /media/ proxy URLs only. */
+    evidence: string[];
+    /**
+     * Which contact details from this incident matched the parent profile.
+     * Stored so the admin can see why this was linked (not for public display).
+     */
+    matchedPhones?: string[];
+    matchedUpiIds?: string[];
+    matchedEmails?: string[];
+    matchedNames?: string[];
+    /**
+     * Incidents follow the same review workflow as top-level profiles.
+     * pending_review → verified | rejected
+     */
+    status: ScammerStatus;
+    verifiedBy?: string;
+    verifiedAt?: Date;
+    createdAt: Date;
+}
+export type ScammerIncidentCreateInput = Pick<ScammerIncidentDocument, "scammerId" | "reportedBy" | "reportedByAnon" | "scamType" | "scamPlatform" | "description" | "amountLost" | "itemInvolved" | "evidence" | "matchedPhones" | "matchedUpiIds" | "matchedEmails" | "matchedNames">;
+export declare const SCAMMER_INCIDENTS_SUBCOLLECTION: "incidents";
+export declare const DEFAULT_SCAMMER_INCIDENT_DATA: Partial<ScammerIncidentDocument>;
+/**
+ * Public comment on a scammer profile page.
+ *
+ * Purpose: victims share additional context; the accused person can post their
+ * side of the story (isAccused flag); admins can post official notes.
+ *
+ * Rules:
+ *  - Requires authentication — no anonymous comments
+ *  - Max 500 chars per comment
+ *  - isAccused is self-declared — admin reviews and can set isAccusedVerified
+ *  - Hidden comments are still stored but not rendered to public
+ */
+export interface ScammerCommentDocument {
+    /** Firestore auto-ID. */
+    id: string;
+    scammerId: string;
+    authorId: string;
+    /** Denormalized — shown on comment. Anonymous if user deleted account. */
+    authorDisplayName: string;
+    authorRole: "user" | "support" | "admin";
+    /**
+     * Self-declared flag: commenter claims to be the person named in this profile.
+     * Admin should review before surfacing with visual "Accused" badge.
+     */
+    isAccused: boolean;
+    /** Set by admin after verification. Governs the public "Accused" badge. */
+    isAccusedVerified?: boolean;
+    /**
+     * True when the commenter had an order matching this scammer's identity
+     * and the orderId is linked — shows "Verified Victim" badge.
+     */
+    isVerifiedVictim: boolean;
+    /** Order ID used to verify victim status. Never shown on public page. */
+    linkedOrderId?: string;
+    /** Plain text, max 500 chars. */
+    body: string;
+    /** Simple upvote count — incremented server-side, never decremented. */
+    upvotes: number;
+    /** Admin moderation — hidden comments stay in DB for audit. */
+    isHidden: boolean;
+    hiddenBy?: string;
+    hiddenReason?: string;
+    createdAt: Date;
+    updatedAt?: Date;
+}
+export type ScammerCommentCreateInput = Pick<ScammerCommentDocument, "scammerId" | "authorId" | "authorDisplayName" | "authorRole" | "isAccused" | "isVerifiedVictim" | "linkedOrderId" | "body">;
+export declare const SCAMMER_COMMENTS_SUBCOLLECTION: "comments";
+export declare const DEFAULT_SCAMMER_COMMENT_DATA: Partial<ScammerCommentDocument>;
+/** Max comment length enforced at API level. */
+export declare const MAX_COMMENT_BODY_LENGTH = 500;
+/**
+ * Dispute submission against a scammer profile.
+ *
+ * Two entry points on the public page:
+ *  1. "I am falsely accused" → type: accused_contesting (the named person)
+ *  2. "Report as inaccurate / false" → type: false_report | inaccurate_details | identity_mistaken
+ *
+ * All contests start as "pending" and surface in the admin moderation queue
+ * (scammerProfiles.isContested = true). Admin upholds or dismisses.
+ * On uphold: admin edits profile manually before marking upheld.
+ * On dismiss: profile status is unchanged; contest is archived.
+ */
+export interface ScammerContestDocument {
+    /** Firestore auto-ID. */
+    id: string;
+    scammerId: string;
+    contestType: ContestType;
+    contestedBy: string;
+    /**
+     * If true, contest submitter is anonymous on public-facing displays.
+     * UID is always stored for admin audit.
+     */
+    contestedByAnon: boolean;
+    /** Contestant's explanation. Plain text, max 2000 chars. */
+    explanation: string;
+    /**
+     * Supporting evidence (e.g. proof of identity, transaction records).
+     * /media/ proxy URLs only.
+     */
+    evidence: string[];
+    status: ContestStatus;
+    /** UID of admin/employee who reviewed. */
+    reviewedBy?: string;
+    reviewedAt?: Date;
+    /** Internal note — never shown to contest submitter or public. */
+    reviewNote?: string;
+    createdAt: Date;
+}
+export type ScammerContestCreateInput = Pick<ScammerContestDocument, "scammerId" | "contestType" | "contestedBy" | "contestedByAnon" | "explanation" | "evidence">;
+export declare const SCAMMER_CONTESTS_SUBCOLLECTION: "contests";
+export declare const DEFAULT_SCAMMER_CONTEST_DATA: Partial<ScammerContestDocument>;
+export declare const CONTEST_TYPE_LABELS: Record<ContestType, string>;
+export declare const CONTEST_STATUS_LABELS: Record<ContestStatus, string>;
+/**
+ * Fields used to detect duplicate scammer profiles when a new report is submitted.
+ * API queries array-contains on each of these fields against the new report's values.
+ * Results are returned as "suggested existing profiles" for the reporter to confirm.
+ *
+ * Priority order: phones > upiIds > emails > displayNames
+ * A match on phones or upiIds is considered a strong match (likely same person).
+ * A match on displayNames only is a weak match (shown as "possibly same person").
+ */
+export declare const SCAMMER_MATCH_FIELDS: readonly ["phones", "upiIds", "emails", "displayNames"];
+export type ScammerMatchField = (typeof SCAMMER_MATCH_FIELDS)[number];
+/** Match strength returned by the suggestion API. */
+export type ScammerMatchStrength = "strong" | "weak";
+export interface ScammerSuggestion {
+    scammerId: string;
+    seoSlug: string;
+    displayNames: string[];
+    status: ScammerStatus;
+    /** Which fields caused this suggestion. */
+    matchedOn: ScammerMatchField[];
+    matchStrength: ScammerMatchStrength;
+}
+export declare const SCAMMER_COLLECTION: "scammerProfiles";
+export declare const SCAMMER_ID_PREFIX: "scammer-";
+export declare const SCAMMER_INDEXED_FIELDS: readonly ["status", "scamType", "scamPlatform", "reportedBy", "verifiedBy", "isContested", "views", "incidentCount", "createdAt", "updatedAt"];
+export declare const DEFAULT_SCAMMER_DATA: Partial<ScammerDocument>;
+/** Max pending submissions per user — prevents spam flooding. */
+export declare const MAX_PENDING_SCAMMER_REPORTS_PER_USER = 5;
+export type ScammerCreateInput = Pick<ScammerDocument, "displayNames" | "phones" | "upiIds" | "emails" | "socialMedia" | "scamType" | "scamPlatform" | "description" | "amountLost" | "itemInvolved" | "evidence" | "reportedBy" | "reportedByAnon">;
+export type ScammerAdminUpdateInput = Partial<Pick<ScammerDocument, "status" | "verifiedBy" | "verifiedAt" | "verificationNote" | "relatedScammerIds" | "mergedFromIds" | "tags" | "displayNames" | "phones" | "upiIds" | "emails" | "socialMedia" | "isContested">>;
+export declare const SCAMMER_FIELDS: {
+    readonly ID: "id";
+    readonly SEO_SLUG: "seoSlug";
+    readonly DISPLAY_NAMES: "displayNames";
+    readonly PHONES: "phones";
+    readonly UPI_IDS: "upiIds";
+    readonly EMAILS: "emails";
+    readonly SOCIAL_MEDIA: "socialMedia";
+    readonly SCAM_TYPE: "scamType";
+    readonly SCAM_PLATFORM: "scamPlatform";
+    readonly DESCRIPTION: "description";
+    readonly AMOUNT_LOST: "amountLost";
+    readonly ITEM_INVOLVED: "itemInvolved";
+    readonly EVIDENCE: "evidence";
+    readonly REPORTED_BY: "reportedBy";
+    readonly REPORTED_BY_ANON: "reportedByAnon";
+    readonly STATUS: "status";
+    readonly VERIFIED_BY: "verifiedBy";
+    readonly VERIFIED_AT: "verifiedAt";
+    readonly VERIFICATION_NOTE: "verificationNote";
+    readonly RELATED_SCAMMER_IDS: "relatedScammerIds";
+    readonly MERGED_FROM_IDS: "mergedFromIds";
+    readonly TAGS: "tags";
+    readonly VIEWS: "views";
+    readonly INCIDENT_COUNT: "incidentCount";
+    readonly COMMENT_COUNT: "commentCount";
+    readonly CONTEST_COUNT: "contestCount";
+    readonly IS_CONTESTED: "isContested";
+    readonly CREATED_AT: "createdAt";
+    readonly UPDATED_AT: "updatedAt";
+};
+export declare const SCAM_PLATFORM_LABELS: Record<ScamPlatform, string>;
+export declare const SOCIAL_PLATFORM_LABELS: Record<SocialPlatform, string>;
+export declare const SCAMMER_STATUS_LABELS: Record<ScammerStatus, string>;