@mohasinac/appkit 4.71.0 → 4.71.2

package/dist/features/faq/actions/faq-actions.js

@@ -1,9 +1,50 @@
-import { sieveFilter, SIEVE_OP } from "@mohasinac/appkit";
+import { SIEVE_OP, sieveFilter } from "../../../utils/sieve-builder.js";
 import { z } from "zod";
 import { serverLogger } from "../../../monitoring/index.js";
 import { sortBy } from "../../../constants/sort.js";
 import { faqsRepository } from "../repository/faqs.repository.js";
+import { isContentVisible } from "../../../_internal/shared/features/content-tags/registry.js";
+import { siteSettingsRepository } from "../../admin/repository/site-settings.repository.js";
+import { resolveFaqAnswer } from "../utils/resolveFaqAnswer.js";
 // --- Schemas --------------------------------------------------------------
+/**
+ * Mirrors `ContentFragment` (`_internal/shared/content/fragments.ts`) — for
+ * an answer that MENTIONS several governed things rather than being solely
+ * about one (document-level `contentTags` already covers that case). Each
+ * fragment's own `governs` is optional (omitted = always-shown clause, e.g.
+ * the answer's opening sentence).
+ *
+ * Exported (added Item 7, 2026-11-04) so the `/api/admin/faqs*` routes — a
+ * SEPARATE write path from this file's own `createFaq`/`updateFaq`, with
+ * their own local Zod schemas — can accept the same field with one
+ * definition instead of a third hand-copy. Those routes are what the admin
+ * FAQ editor UI actually calls; `answerFragments` existing only here, with
+ * no reader on the path the UI uses, would mean an editor that appears to
+ * save but silently drops the field on every write.
+ */
+export const answerFragmentsSchema = z
+    .array(z.object({
+    // Mirrors `ContentTag` verbatim (not a `{kind, value}` wrapper) — a
+    // fragment's `governs` IS a `ContentTag`, passed straight into
+    // `isContentVisible([f.governs], settings)` with no reshaping.
+    governs: z
+        .object({
+        governs: z.enum(["listingType", "categoryType", "browsePage"]),
+        value: z.string().min(1).max(50),
+    })
+        .optional(),
+    text: z.string().min(1).max(2000),
+    /*
+     * Item 7 (2026-11-03) — replacement text used when `governs` is
+     * disabled, instead of omitting the fragment. "If an FAQ mentions
+     * pre-orders and I disable them, replace that wording, don't hide
+     * the FAQ." Optional; omitted keeps the pre-existing omit-on-disable
+     * behavior.
+     */
+    whenHidden: z.string().min(1).max(2000).optional(),
+}))
+    .max(20)
+    .optional();
 const faqBaseSchema = z.object({
     question: z.string().min(10).max(500),
     answer: z.object({
@@ -18,6 +59,27 @@ const faqBaseSchema = z.object({
     isPinned: z.boolean().default(false),
     order: z.number().int().min(0).default(0),
     tags: z.array(z.string().min(1).max(50)).max(10).optional(),
+    /*
+     * Mirrors `ContentTag` (`_internal/shared/features/content-tags/registry.ts`) —
+     * `governs` stays a plain string enum here rather than importing the type,
+     * since this is the request-validation boundary and a Zod enum gives a
+     * clearer 400 than a TS type ever would.
+     */
+    contentTags: z
+        .array(z.object({
+        governs: z.enum(["listingType", "categoryType", "browsePage"]),
+        value: z.string().min(1).max(50),
+    }))
+        .max(10)
+        .optional(),
+    /*
+     * Mirrors `ContentFragment` (`_internal/shared/content/fragments.ts`) — for
+     * an answer that MENTIONS several governed things rather than being solely
+     * about one (which `contentTags` above already covers). Each fragment's own
+     * `governs` is optional (omitted = always-shown clause, e.g. the answer's
+     * opening sentence).
+     */
+    answerFragments: answerFragmentsSchema,
     relatedFAQs: z.array(z.string()).max(5).optional(),
     useSiteSettings: z.boolean().default(true),
     variables: z.record(z.string(), z.string()).optional(),
@@ -94,7 +156,22 @@ export async function listPublicFaqs(category, limit = 20) {
         page: 1,
         pageSize: limit,
     });
-    return result.items;
+    /*
+     * In-memory post-filter, same technique `listPublicProducts`'s `finish()`
+     * already uses for listing-type visibility — a Firestore equality query
+     * cannot express "none of this FAQ's N tags is for a disabled thing"
+     * (CLAUDE.md § "Availability & Order-Scope Tabs" explains why the dense/
+     * negation-shaped case always stays a per-row predicate). First real
+     * consumer of `contentTags`/`isContentVisible` (1A), and the first real
+     * consumer of `getFlagSnapshot()`'s 30-minute flag cache (1A-iv) — this
+     * reads settings purely to check flags, never anything else off the
+     * document, so the narrower, longer-lived cache is a strict win here over
+     * `getSingleton()`'s 60s whole-document one.
+     */
+    const settings = await siteSettingsRepository.getFlagSnapshot();
+    return result.items
+        .filter((faq) => isContentVisible(faq.contentTags, settings))
+        .map((faq) => resolveFaqAnswer(faq, settings));
 }
 export async function getFaqById(id) {
     return faqsRepository.findById(id);

package/dist/features/faq/components/FAQAccordion.js

@@ -4,6 +4,7 @@ import { useState } from "react";
 import { Button } from "../../../ui/components/Button.js";
 import { Div } from "../../../ui/components/Div.js";
 import { RichText } from "../../../ui/rich-text/RichText.js";
+import { LiveEditableRegion } from "../../../ui/components/LiveEditableRegion.js";
 import { Row } from "../../../ui/components/Layout.js";
 import { Span, Text } from "../../../ui/components/Typography.js";
 import { Tabs, TabsList, TabsTrigger } from "../../../ui/components/Tabs.js";
@@ -34,7 +35,7 @@ import { RecordOwnerQuickActions } from "../../admin/components/RecordOwnerQuick
  */
 const CODE_DERIVED_VALUES = resolvePublishedValues();
 function FAQAccordionItem({ faq, isOpen, onToggle, renderExpandedFooter, publishedValues = CODE_DERIVED_VALUES, }) {
-    return (_jsxs(Div, { className: "border-b border-neutral-200 last:border-0", children: [_jsxs(Button, { variant: "ghost", onClick: onToggle, "aria-expanded": isOpen, justify: "between", className: "w-full gap-[1rem] py-[1rem] text-left text-[0.875rem] font-[500] text-[var(--appkit-color-text)] dark:text-[var(--appkit-color-text)] transition hover:text-primary", children: [_jsx(Span, { children: faq.question }), _jsx(Span, { className: `flex-shrink-0 transition-transform ${isOpen ? "rotate-180" : ""}`, children: _jsx("svg", { width: "16", height: "16", viewBox: "0 0 16 16", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "M4 6l4 4 4-4", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round" }) }) })] }), isOpen && (_jsxs(Div, { textSize: "sm", className: "text-[var(--appkit-color-text-muted)]", padding: "b-md", children: [faq.tags && faq.tags.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mb-3", children: faq.tags.map((tag) => (_jsx(Span, { className: "bg-[var(--appkit-color-surface)] py-[0.25rem] text-[var(--appkit-color-text-muted)]", rounded: "md", padding: "x-xs", size: "xs", children: tag }, tag))) })), faq.answer.format === "html" ? (_jsx(RichText, { html: resolvePublishedCopy(faq.answer.text, publishedValues), className: "prose-sm" })) : (_jsx(Text, { className: "whitespace-pre-line", children: resolvePublishedCopy(faq.answer.text, publishedValues) })), _jsx(Row, { justify: "end", className: "mt-3", children: _jsx(RecordOwnerQuickActions, { resource: "FAQ", recordId: faq.id, placement: "detail", recordLabel: faq.question }) }), renderExpandedFooter?.(faq)] }))] }));
+    return (_jsxs(Div, { className: "border-b border-neutral-200 last:border-0", children: [_jsxs(Button, { variant: "ghost", onClick: onToggle, "aria-expanded": isOpen, justify: "between", className: "w-full gap-[1rem] py-[1rem] text-left text-[0.875rem] font-[500] text-[var(--appkit-color-text)] dark:text-[var(--appkit-color-text)] transition hover:text-primary", children: [_jsx(Span, { children: faq.question }), _jsx(Span, { className: `flex-shrink-0 transition-transform ${isOpen ? "rotate-180" : ""}`, children: _jsx("svg", { width: "16", height: "16", viewBox: "0 0 16 16", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "M4 6l4 4 4-4", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round" }) }) })] }), isOpen && (_jsxs(Div, { textSize: "sm", className: "text-[var(--appkit-color-text-muted)]", padding: "b-md", children: [faq.tags && faq.tags.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mb-3", children: faq.tags.map((tag) => (_jsx(Span, { className: "bg-[var(--appkit-color-surface)] py-[0.25rem] text-[var(--appkit-color-text-muted)]", rounded: "md", padding: "x-xs", size: "xs", children: tag }, tag))) })), _jsx(LiveEditableRegion, { contentType: "faq", id: faq.id, field: "answer", value: faq.answer.text, renderValue: (raw) => faq.answer.format === "html" ? (_jsx(RichText, { html: resolvePublishedCopy(raw, publishedValues), className: "prose-sm" })) : (_jsx(Text, { className: "whitespace-pre-line", children: resolvePublishedCopy(raw, publishedValues) })) }), _jsx(Row, { justify: "end", className: "mt-3", children: _jsx(RecordOwnerQuickActions, { resource: "FAQ", recordId: faq.id, placement: "detail", recordLabel: faq.question }) }), renderExpandedFooter?.(faq)] }))] }));
 }
 export function FAQAccordion({ faqs, className = "", renderExpandedFooter, labels, publishedValues, }) {
     const [openId, setOpenId] = useState(null);

package/dist/features/faq/manifest.js

@@ -1,8 +1,16 @@
+/*
+ * Corrected 2026-11 (Phase 2F) — the real canonical route is the PLURAL
+ * `[locale]/faqs`; `[locale]/faq` (singular) is only a redirect shim to it.
+ * The `[category]` detail route was missing entirely.
+ */
 export const manifest = {
     name: "faq",
     i18nNamespace: "faq",
     envKeys: [],
-    routes: [{ segment: "[locale]/faq", exports: { default: "FAQPageView" } }],
+    routes: [
+        { segment: "[locale]/faqs", exports: { default: "FAQPageView" } },
+        { segment: "[locale]/faqs/[category]", exports: { default: "FAQPageView" } },
+    ],
     apiRoutes: [
         { segment: "api/faqs", methods: ["GET", "POST"] },
         { segment: "api/faqs/[id]", methods: ["GET", "PATCH", "DELETE"] },

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

@@ -4,6 +4,10 @@
 import type { FAQCategory, FAQAnswer, FAQStats } from "../types";
 export type { FAQCategory, FAQAnswer, FAQStats } from "../types";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import type { ContentTag } from "../../../_internal/shared/features/content-tags/registry";
+export type { ContentTag } from "../../../_internal/shared/features/content-tags/registry";
+import type { ContentFragment } from "../../../_internal/shared/content/fragments";
+export type { ContentFragment } from "../../../_internal/shared/content/fragments";
 import { extractPlaceholders } from "../../../_internal/shared/templating/placeholders";
 export interface FAQSEO {
     slug: string;
@@ -20,6 +24,27 @@ export interface FAQDocument extends BaseDocument {
     order: number;
     priority: number;
     tags: string[];
+    /**
+     * The flags this FAQ's content depends on, if any. A FAQ explaining how
+     * collector-drop bidding works tags `{ governs: "listingType", value:
+     * "collector-drop" }` — when that type is disabled, the FAQ stops being
+     * served rather than instructing a buyer on a feature they cannot reach.
+     * Absent/empty means always visible (see `isContentVisible`).
+     */
+    contentTags?: ContentTag[];
+    /**
+     * Fragment-level content cascade — for a FAQ that MENTIONS several
+     * governed things without being solely about any one of them (e.g. "What
+     * are the different ways to buy on LetItRip?" naming standard/auction/
+     * pre-order). Distinct from `contentTags` (whole-document hide, above):
+     * when present, `answerFragments` OVERRIDES `answer.text` at render time,
+     * resolved via `resolveFragmentedAnswer()`
+     * (`_internal/shared/content/fragments.ts`) — a disabled fragment's
+     * `governs` tag drops just that clause, the FAQ stays visible. `answer.text`
+     * stays the fallback for FAQs with no governed mentions, and remains the
+     * `searchTxt`-indexing source either way.
+     */
+    answerFragments?: ContentFragment[];
     /** Normalized edge-n-gram search field. Replaced `searchTokens`. */
     searchTxt?: string[];
     relatedFAQs: string[];
@@ -38,7 +63,7 @@ export declare const FAQ_CATEGORY_LABELS: Record<FAQCategory, string>;
 export declare const DEFAULT_FAQ_DATA: Partial<FAQDocument>;
 export declare const FAQS_PUBLIC_FIELDS: readonly ["id", "question", "answer", "category", "showOnHomepage", "showInFooter", "isPinned", "order", "priority", "tags", "relatedFAQs", "stats.views", "stats.helpful", "stats.notHelpful", "seo.slug", "seo.metaTitle", "seo.metaDescription", "isActive", "createdAt"];
 export type FAQCreateInput = Omit<FAQDocument, "id" | "createdAt" | "updatedAt" | "stats">;
-export type FAQUpdateInput = Partial<Pick<FAQDocument, "question" | "answer" | "category" | "showOnHomepage" | "showInFooter" | "isPinned" | "order" | "priority" | "tags" | "relatedFAQs" | "useSiteSettings" | "variables" | "seo" | "isActive">>;
+export type FAQUpdateInput = Partial<Pick<FAQDocument, "question" | "answer" | "category" | "showOnHomepage" | "showInFooter" | "isPinned" | "order" | "priority" | "tags" | "contentTags" | "relatedFAQs" | "useSiteSettings" | "variables" | "seo" | "isActive">>;
 export interface FAQWithInterpolatedAnswer extends Omit<FAQDocument, "answer"> {
     answer: FAQAnswer & {
         interpolated: string;

package/dist/features/faq/schemas/firestore.js

@@ -40,6 +40,7 @@ export const DEFAULT_FAQ_DATA = {
     order: 0,
     priority: 0,
     tags: [],
+    contentTags: [],
     searchTxt: [],
     relatedFAQs: [],
     useSiteSettings: true,

package/dist/features/faq/schemas/index.d.ts

@@ -143,16 +143,16 @@ export declare const faqListParamsSchema: z.ZodObject<{
     pageSize: z.ZodOptional<z.ZodNumber>;
     perPage: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
+    q?: string | undefined;
     category?: "orders_payment" | "shipping_delivery" | "returns_refunds" | "product_information" | "account_security" | "technical_support" | "general" | undefined;
     page?: number | undefined;
-    q?: string | undefined;
     pageSize?: number | undefined;
     perPage?: number | undefined;
     homepage?: boolean | undefined;
 }, {
+    q?: string | undefined;
     category?: "orders_payment" | "shipping_delivery" | "returns_refunds" | "product_information" | "account_security" | "technical_support" | "general" | undefined;
     page?: number | undefined;
-    q?: string | undefined;
     pageSize?: number | undefined;
     perPage?: number | undefined;
     homepage?: boolean | undefined;

package/dist/features/faq/utils/getHomepageFaqsCached.d.ts

@@ -16,5 +16,14 @@
  * Takes no arguments on purpose: `React.cache` memoises per argument list, so a
  * parameterised version would give each distinct call its own entry and dedupe
  * nothing.
+ *
+ * 🛑 Filters by `isContentVisible` (1A) — `faqsRepository.getHomepageFAQs()`
+ * cannot express "none of this FAQ's tags is for a disabled thing" as a
+ * Firestore query, so this is the same in-memory post-filter
+ * `listPublicFaqs`/`listPublicProducts` already use. `siteSettingsRepository.getFlagSnapshot()`
+ * (1A-iv) carries its own 30-minute internal TTL cache (`CacheManager`) —
+ * longer-lived than `getSingleton()`'s 60s, since this reads settings purely
+ * for the flag check and nothing else off the document — so this adds no
+ * new uncached read.
  */
 export declare const getHomepageFaqsCached: () => Promise<import("..").FAQDocument[]>;

package/dist/features/faq/utils/getHomepageFaqsCached.js

@@ -1,5 +1,8 @@
 import { cache } from "react";
 import { faqsRepository } from "../repository/faqs.repository.js";
+import { siteSettingsRepository } from "../../admin/repository/site-settings.repository.js";
+import { isContentVisible } from "../../../_internal/shared/features/content-tags/registry.js";
+import { resolveFaqAnswer } from "./resolveFaqAnswer.js";
 /**
  * React.cache deduplication — one Firestore read per RSC request tree.
  *
@@ -18,5 +21,22 @@ import { faqsRepository } from "../repository/faqs.repository.js";
  * Takes no arguments on purpose: `React.cache` memoises per argument list, so a
  * parameterised version would give each distinct call its own entry and dedupe
  * nothing.
+ *
+ * 🛑 Filters by `isContentVisible` (1A) — `faqsRepository.getHomepageFAQs()`
+ * cannot express "none of this FAQ's tags is for a disabled thing" as a
+ * Firestore query, so this is the same in-memory post-filter
+ * `listPublicFaqs`/`listPublicProducts` already use. `siteSettingsRepository.getFlagSnapshot()`
+ * (1A-iv) carries its own 30-minute internal TTL cache (`CacheManager`) —
+ * longer-lived than `getSingleton()`'s 60s, since this reads settings purely
+ * for the flag check and nothing else off the document — so this adds no
+ * new uncached read.
  */
-export const getHomepageFaqsCached = cache(() => faqsRepository.getHomepageFAQs());
+export const getHomepageFaqsCached = cache(async () => {
+    const [faqs, settings] = await Promise.all([
+        faqsRepository.getHomepageFAQs(),
+        siteSettingsRepository.getFlagSnapshot(),
+    ]);
+    return faqs
+        .filter((faq) => isContentVisible(faq.contentTags, settings))
+        .map((faq) => resolveFaqAnswer(faq, settings));
+});

package/dist/features/faq/utils/resolveFaqAnswer.d.ts

@@ -0,0 +1,9 @@
+import type { FAQDocument } from "../schemas/firestore";
+import { type ContentFlagSnapshot } from "../../../_internal/shared/content/fragments";
+/**
+ * Overrides `answer.text` with the resolved `answerFragments` join, when
+ * present — server-side, before the FAQ reaches `FAQAccordion.tsx`, which
+ * keeps reading `faq.answer.text` exactly as it did before `answerFragments`
+ * existed. A FAQ with no `answerFragments` is returned unchanged.
+ */
+export declare function resolveFaqAnswer(faq: FAQDocument, settings: ContentFlagSnapshot | null | undefined): FAQDocument;

package/dist/features/faq/utils/resolveFaqAnswer.js

@@ -0,0 +1,18 @@
+import { resolveFragmentedAnswer, } from "../../../_internal/shared/content/fragments.js";
+/**
+ * Overrides `answer.text` with the resolved `answerFragments` join, when
+ * present — server-side, before the FAQ reaches `FAQAccordion.tsx`, which
+ * keeps reading `faq.answer.text` exactly as it did before `answerFragments`
+ * existed. A FAQ with no `answerFragments` is returned unchanged.
+ */
+export function resolveFaqAnswer(faq, settings) {
+    if (!faq.answerFragments || faq.answerFragments.length === 0)
+        return faq;
+    return {
+        ...faq,
+        answer: {
+            ...faq.answer,
+            text: resolveFragmentedAnswer(faq.answerFragments, settings),
+        },
+    };
+}

package/dist/features/gateway-events/schemas/index.d.ts

@@ -28,8 +28,8 @@ export declare const gatewayEventFirestoreSchema: z.ZodObject<{
     updatedAt: z.ZodDate;
     seedPurpose: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    status: "received" | "processing" | "failed" | "processed" | "conflict" | "ignored";
     id: string;
+    status: "received" | "processing" | "failed" | "processed" | "conflict" | "ignored";
     createdAt: Date;
     updatedAt: Date;
     expiresAt: Date;
@@ -53,8 +53,8 @@ export declare const gatewayEventFirestoreSchema: z.ZodObject<{
     providerEventId?: string | undefined;
     payloadTruncated?: boolean | undefined;
 }, {
-    status: "received" | "processing" | "failed" | "processed" | "conflict" | "ignored";
     id: string;
+    status: "received" | "processing" | "failed" | "processed" | "conflict" | "ignored";
     createdAt: Date;
     updatedAt: Date;
     expiresAt: Date;

package/dist/features/giveaway/repository/giveaway-entry.repository.d.ts

@@ -0,0 +1,48 @@
+import type { FirebaseSieveFields, FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
+import { BaseRepository } from "../../../providers/db-firebase";
+import { type GiveawayEntryDocument, type GiveawayEntryPlain } from "../schemas/firestore";
+declare class GiveawayEntryRepository extends BaseRepository<GiveawayEntryDocument> {
+    static readonly SIEVE_FIELDS: FirebaseSieveFields;
+    constructor();
+    /**
+     * Plaintext PII. **Opt-in and named** — for the admin entries table and the
+     * draw notification, where the real address is the point.
+     */
+    revealEntry(doc: GiveawayEntryDocument): GiveawayEntryPlain;
+    /** As `revealEntry`, for a list read. */
+    revealEntries(docs: readonly GiveawayEntryDocument[]): GiveawayEntryPlain[];
+    /**
+     * Masked PII — **the default for any surface that only needs to identify a
+     * row to a human.** Decrypts first, then masks: handing a stored field
+     * straight to `maskName` would return "Anonymous" for every row, because
+     * those helpers refuse ciphertext by design.
+     */
+    maskedEntry(doc: GiveawayEntryDocument): GiveawayEntryPlain;
+    /** As `maskedEntry`, for a list read. */
+    maskedEntries(docs: readonly GiveawayEntryDocument[]): GiveawayEntryPlain[];
+    /**
+     * Get the next sequential userGiveawayNumber for a source atomically.
+     * Returns current count + 1.
+     */
+    nextUserGiveawayNumber(sourceId: string, field: "eventId" | "productId"): Promise<number>;
+    /**
+     * Count entries for a given source and transaction ID.
+     * Used to enforce maxPullsPerTransaction.
+     */
+    countByTransactionId(sourceId: string, sourceField: "eventId" | "productId", transactionId: string): Promise<number>;
+    /**
+     * Count entries for a given source and user.
+     * Used to enforce maxPullsPerUser.
+     */
+    countByUser(sourceId: string, sourceField: "eventId" | "productId", userId: string): Promise<number>;
+    /** List all entries for an event/product source. Paginated via Sieve. */
+    listForSource(sourceId: string, sourceField: "eventId" | "productId", model: SieveModel): Promise<FirebaseSieveResult<GiveawayEntryDocument>>;
+    /** List entries for a specific user across all sources. */
+    listForUser(userId: string, model: SieveModel): Promise<FirebaseSieveResult<GiveawayEntryDocument>>;
+    /** Create a giveaway entry with PII encryption. */
+    createEntry(data: Omit<GiveawayEntryPlain, "id">): Promise<GiveawayEntryDocument>;
+    /** Flag a giveaway entry as fraudulent. */
+    flagEntry(entryId: string, flagNote: string, flaggedBy: string): Promise<GiveawayEntryDocument>;
+}
+export { GiveawayEntryRepository };
+export declare const giveawayEntryRepository: GiveawayEntryRepository;

package/dist/features/giveaway/repository/giveaway-entry.repository.js

@@ -0,0 +1,172 @@
+import { normalizeError } from "../../../errors/normalize.js";
+import { DatabaseError } from "../../../errors/index.js";
+import { serverLogger } from "../../../monitoring/index.js";
+import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
+import { encryptPiiFields, maskPii, revealPii, GIVEAWAY_ENTRY_PII_FIELDS, } from "../../../security/index.js";
+import { GIVEAWAY_ENTRIES_COLLECTION, GIVEAWAY_ENTRY_FIELDS, } from "../schemas/firestore.js";
+class GiveawayEntryRepository extends BaseRepository {
+    constructor() {
+        super(GIVEAWAY_ENTRIES_COLLECTION);
+    }
+    /*
+     * 🛑 `mapDoc` is NOT overridden, and that is the whole change.
+     *
+     * It used to call `decryptPiiFields` on every read, so ciphertext never left
+     * the database and all five consumers handled plaintext without ever saying
+     * so. Following `SiteSettingsRepository`: reads return what Firestore holds,
+     * and plaintext requires one of the two named methods below.
+     *
+     * The compiler enforces it rather than a convention doing so —
+     * `GiveawayEntryDocument`'s PII fields are `Encrypted<string>`, assignable to
+     * nothing that wants a plain `string`, so a reader that skips both accessors
+     * is a compile error naming the file and line.
+     */
+    /**
+     * Plaintext PII. **Opt-in and named** — for the admin entries table and the
+     * draw notification, where the real address is the point.
+     */
+    revealEntry(doc) {
+        return revealPii(doc, GIVEAWAY_ENTRY_PII_FIELDS);
+    }
+    /** As `revealEntry`, for a list read. */
+    revealEntries(docs) {
+        return docs.map((d) => this.revealEntry(d));
+    }
+    /**
+     * Masked PII — **the default for any surface that only needs to identify a
+     * row to a human.** Decrypts first, then masks: handing a stored field
+     * straight to `maskName` would return "Anonymous" for every row, because
+     * those helpers refuse ciphertext by design.
+     */
+    maskedEntry(doc) {
+        return maskPii(doc, GIVEAWAY_ENTRY_PII_FIELDS);
+    }
+    /** As `maskedEntry`, for a list read. */
+    maskedEntries(docs) {
+        return docs.map((d) => this.maskedEntry(d));
+    }
+    /**
+     * Get the next sequential userGiveawayNumber for a source atomically.
+     * Returns current count + 1.
+     */
+    async nextUserGiveawayNumber(sourceId, field) {
+        try {
+            const snapshot = await this.getCollection()
+                .where(field, "==", sourceId)
+                .get();
+            return snapshot.size + 1;
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to get next giveaway number for ${field}=${sourceId}`, error);
+        }
+    }
+    /**
+     * Count entries for a given source and transaction ID.
+     * Used to enforce maxPullsPerTransaction.
+     */
+    async countByTransactionId(sourceId, sourceField, transactionId) {
+        try {
+            const snapshot = await this.getCollection()
+                .where(sourceField, "==", sourceId)
+                .where(GIVEAWAY_ENTRY_FIELDS.TRANSACTION_ID, "==", transactionId)
+                .get();
+            return snapshot.size;
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to count entries for transactionId=${transactionId}`, error);
+        }
+    }
+    /**
+     * Count entries for a given source and user.
+     * Used to enforce maxPullsPerUser.
+     */
+    async countByUser(sourceId, sourceField, userId) {
+        try {
+            const snapshot = await this.getCollection()
+                .where(sourceField, "==", sourceId)
+                .where(GIVEAWAY_ENTRY_FIELDS.USER_ID, "==", userId)
+                .where(GIVEAWAY_ENTRY_FIELDS.STATUS, "!=", "cancelled")
+                .get();
+            return snapshot.size;
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to count entries for userId=${userId}`, error);
+        }
+    }
+    /** List all entries for an event/product source. Paginated via Sieve. */
+    async listForSource(sourceId, sourceField, model) {
+        return this.sieveQuery(model, GiveawayEntryRepository.SIEVE_FIELDS, {
+            baseQuery: this.getCollection().where(sourceField, "==", sourceId),
+        });
+    }
+    /** List entries for a specific user across all sources. */
+    async listForUser(userId, model) {
+        return this.sieveQuery(model, GiveawayEntryRepository.SIEVE_FIELDS, {
+            baseQuery: this.getCollection().where(GIVEAWAY_ENTRY_FIELDS.USER_ID, "==", userId),
+        });
+    }
+    /** Create a giveaway entry with PII encryption. */
+    /*
+     * 🛑 Takes PLAINTEXT (`GiveawayEntryPlain`), returns CIPHERTEXT
+     * (`GiveawayEntryDocument`), and the asymmetry is the point.
+     *
+     * The caller holds a real email and phone; this method encrypts them. Typing
+     * the parameter `Omit<GiveawayEntryDocument, "id">` would have demanded the
+     * caller hand over `Encrypted<string>` it does not have, and the only way to
+     * satisfy that is `asEncrypted(email)` — which labels plaintext as ciphertext
+     * and is exactly the misuse `asEncrypted`'s own docstring forbids. The
+     * encryption happens here; so does the type change.
+     */
+    async createEntry(data) {
+        try {
+            const encrypted = encryptPiiFields(data, [...GIVEAWAY_ENTRY_PII_FIELDS]);
+            const prepared = prepareForFirestore({ ...encrypted });
+            const ref = await this.getCollection().add(prepared);
+            const created = await ref.get();
+            serverLogger.info("Giveaway entry created", {
+                entryId: ref.id,
+                sourceType: data.sourceType,
+                eventId: data.eventId,
+                productId: data.productId,
+                userId: data.userId,
+                userGiveawayNumber: data.userGiveawayNumber,
+            });
+            return this.mapDoc(created);
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError("Failed to create giveaway entry", error);
+        }
+    }
+    /** Flag a giveaway entry as fraudulent. */
+    async flagEntry(entryId, flagNote, flaggedBy) {
+        try {
+            await this.getCollection().doc(entryId).update(prepareForFirestore({
+                isFlagged: true,
+                flagNote,
+                flaggedBy,
+                flaggedAt: new Date(),
+                status: "flagged",
+            }));
+            return this.findByIdOrFail(entryId);
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to flag giveaway entry ${entryId}`, error);
+        }
+    }
+}
+GiveawayEntryRepository.SIEVE_FIELDS = {
+    sourceType: { canFilter: true, canSort: false },
+    eventId: { canFilter: true, canSort: false },
+    productId: { canFilter: true, canSort: false },
+    userId: { canFilter: true, canSort: false },
+    status: { canFilter: true, canSort: false },
+    submittedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    userGiveawayNumber: { canFilter: false, canSort: true },
+};
+export { GiveawayEntryRepository };
+export const giveawayEntryRepository = new GiveawayEntryRepository();