@mohasinac/appkit 4.61.0 → 4.62.1

package/dist/features/dispute-reasons/schemas/firestore.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `disputeReasons` — the staff-curated list a buyer picks from when raising a
+ * dispute.
+ *
+ * ## What this is NOT
+ *
+ * 🛑 It is not policy. Every row carries a `kind`, and the GATE lives on the
+ * kind — see `_internal/shared/features/orders/dispute-reasons.ts`. A row can
+ * never introduce a new kind of claim, because a gate cannot branch on a
+ * user-created string.
+ *
+ * So this list is for TRIAGE and ANALYTICS: "what are buyers actually
+ * reporting", answered without reading free text. Staff (admin + employees)
+ * add rows as real gaps appear; buyers select only.
+ *
+ * ## Why staff-creatable rather than a closed enum
+ *
+ * Its sibling `RETURN_REASON` *is* a closed enum, and deliberately so: each
+ * member there decides whether a final sale can refuse the return, which is a
+ * money consequence that must be reviewed in code. Nothing here decides money.
+ * A support agent who keeps seeing "the courier left it at the wrong flat"
+ * should be able to add it without a release.
+ */
+import type { DisputeKind } from "../../../_internal/shared/features/orders/dispute-reasons";
+export declare const DISPUTE_REASON_COLLECTION = "disputeReasons";
+export interface DisputeReasonDocument {
+    /** `dreason-<slug of label>`, so the same reason cannot be added twice. */
+    id: string;
+    /** Buyer-facing. Shown verbatim in the picker. */
+    label: string;
+    /** Which gate this reason is subject to. Never free-form. */
+    kind: DisputeKind;
+    /**
+     * 🛑 Soft-retire, never delete.
+     *
+     * A past dispute names this reason. Deleting the row would orphan that
+     * record and take the author with it — and the order snapshots the LABEL
+     * precisely so history survives either way, but a deleted row still loses
+     * "who added this, and when" for anyone auditing the list itself.
+     */
+    isActive: boolean;
+    /** Display name, so a seller or agent can see whose wording this is. */
+    createdByName: string;
+    /** The uid, for moderation. Never rendered. */
+    createdByUid: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export declare const DISPUTE_REASON_FIELDS: {
+    readonly ID: "id";
+    readonly LABEL: "label";
+    readonly KIND: "kind";
+    readonly IS_ACTIVE: "isActive";
+    readonly CREATED_BY_UID: "createdByUid";
+    readonly CREATED_AT: "createdAt";
+};
+/**
+ * Bounds on a label.
+ *
+ * Short on purpose: this is a picker option, not the buyer's explanation. The
+ * detail goes in the free-text field on the dispute itself, which is where a
+ * buyer should describe what actually happened.
+ */
+export declare const DISPUTE_REASON_LABEL_MAX = 80;

package/dist/features/dispute-reasons/schemas/firestore.js

@@ -0,0 +1,40 @@
+/**
+ * `disputeReasons` — the staff-curated list a buyer picks from when raising a
+ * dispute.
+ *
+ * ## What this is NOT
+ *
+ * 🛑 It is not policy. Every row carries a `kind`, and the GATE lives on the
+ * kind — see `_internal/shared/features/orders/dispute-reasons.ts`. A row can
+ * never introduce a new kind of claim, because a gate cannot branch on a
+ * user-created string.
+ *
+ * So this list is for TRIAGE and ANALYTICS: "what are buyers actually
+ * reporting", answered without reading free text. Staff (admin + employees)
+ * add rows as real gaps appear; buyers select only.
+ *
+ * ## Why staff-creatable rather than a closed enum
+ *
+ * Its sibling `RETURN_REASON` *is* a closed enum, and deliberately so: each
+ * member there decides whether a final sale can refuse the return, which is a
+ * money consequence that must be reviewed in code. Nothing here decides money.
+ * A support agent who keeps seeing "the courier left it at the wrong flat"
+ * should be able to add it without a release.
+ */
+export const DISPUTE_REASON_COLLECTION = "disputeReasons";
+export const DISPUTE_REASON_FIELDS = {
+    ID: "id",
+    LABEL: "label",
+    KIND: "kind",
+    IS_ACTIVE: "isActive",
+    CREATED_BY_UID: "createdByUid",
+    CREATED_AT: "createdAt",
+};
+/**
+ * Bounds on a label.
+ *
+ * Short on purpose: this is a picker option, not the buyer's explanation. The
+ * detail goes in the free-text field on the dispute itself, which is where a
+ * buyer should describe what actually happened.
+ */
+export const DISPUTE_REASON_LABEL_MAX = 80;

package/dist/features/events/components/AdminEventEditorView.js

@@ -407,10 +407,10 @@ export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes,
             // The per-step `validate` is gone: every rule it stated is already in
             // eventDraftSchema (title/startsAt/endsAt are .min(1)), and it only ever
             // acted as a gate to the next step.
-            render: ({ values, onChange }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Event Details" }), !isEdit && (_jsx(Select, { label: "Event type", value: values.type, options: allowedTypes ? EVENT_TYPE_OPTIONS.filter((o) => allowedTypes.includes(o.value)) : EVENT_TYPE_OPTIONS, onChange: (e) => onChange({ type: e.target.value }) })), _jsx(Input, { label: "Title", value: values.title, onChange: (e) => {
+            render: ({ values, onChange, errors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Event Details" }), !isEdit && (_jsx(Select, { label: "Event type", error: errors.type, value: values.type, options: allowedTypes ? EVENT_TYPE_OPTIONS.filter((o) => allowedTypes.includes(o.value)) : EVENT_TYPE_OPTIONS, onChange: (e) => onChange({ type: e.target.value }) })), _jsx(Input, { label: "Title", error: errors.title, value: values.title, onChange: (e) => {
                             const v = e.target.value;
                             onChange({ title: v, ...(!slugManual && { slug: toEventSlug(v) }) });
-                        }, placeholder: "Charizard Flash Sale 2026", required: true }), _jsx(Input, { label: "Slug", value: values.slug, onChange: (e) => { setSlugManual(true); onChange({ slug: e.target.value }); }, placeholder: "event-charizard-flash-sale-2026", helperText: "Auto-generated from title. Must start with 'event-'." }), _jsxs(Stack, { gap: "xs", children: [_jsx(Label, { children: "Description" }), _jsx(RichTextEditor, { value: values.description, onChange: (v) => onChange({ description: v }), minHeightClassName: "min-h-[120px]", placeholder: "Describe this event\u2026" })] }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Starts at", type: "datetime-local", value: values.startsAt, onChange: (e) => onChange({ startsAt: e.target.value }), required: true }), _jsx(Input, { label: "Ends at", type: "datetime-local", value: values.endsAt, onChange: (e) => onChange({ endsAt: e.target.value }), required: true })] }), _jsx(TagInput, { label: "Tags", value: values.tags, onChange: (t) => onChange({ tags: t }), placeholder: "e.g. pokemon, sale, 2026" })] })),
+                        }, placeholder: "Charizard Flash Sale 2026", required: true }), _jsx(Input, { label: "Slug", error: errors.slug, value: values.slug, onChange: (e) => { setSlugManual(true); onChange({ slug: e.target.value }); }, placeholder: "event-charizard-flash-sale-2026", helperText: "Auto-generated from title. Must start with 'event-'." }), _jsxs(Stack, { gap: "xs", children: [_jsx(Label, { children: "Description" }), _jsx(RichTextEditor, { value: values.description, onChange: (v) => onChange({ description: v }), minHeightClassName: "min-h-[120px]", placeholder: "Describe this event\u2026" })] }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Starts at", error: errors.startsAt, type: "datetime-local", value: values.startsAt, onChange: (e) => onChange({ startsAt: e.target.value }), required: true }), _jsx(Input, { label: "Ends at", error: errors.endsAt, type: "datetime-local", value: values.endsAt, onChange: (e) => onChange({ endsAt: e.target.value }), required: true })] }), _jsx(TagInput, { label: "Tags", value: values.tags, onChange: (t) => onChange({ tags: t }), placeholder: "e.g. pokemon, sale, 2026" })] })),
         },
         {
             id: "media",
@@ -419,7 +419,7 @@ export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes,
             // section mid-upload discards the transfer.
             keepMounted: true,
             fields: ["coverImageUrl"],
-            render: ({ values, onChange }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Media" }), _jsx(Input, { label: "Cover Image URL (optional)", value: values.coverImageUrl, onChange: (e) => onChange({ coverImageUrl: e.target.value }), placeholder: "https://\u2026", helperText: "Direct link to the event cover image." })] })),
+            render: ({ values, onChange, errors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Media" }), _jsx(Input, { label: "Cover Image URL (optional)", error: errors.coverImageUrl, value: values.coverImageUrl, onChange: (e) => onChange({ coverImageUrl: e.target.value }), placeholder: "https://\u2026", helperText: "Direct link to the event cover image." })] })),
         },
         {
             id: "settings",
@@ -428,17 +428,19 @@ export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes,
             // Same: the offer-coupon, offer-display-code and poll-minimum-options
             // rules are all stated in eventDraftSchema's superRefine, which now
             // surfaces them inline on the field instead of as a step-blocking banner.
-            render: ({ values, onChange }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Event Settings" }), isEdit && (_jsx(Select, { label: "Status", value: values.status, options: EVENT_STATUS_OPTIONS, onChange: (e) => onChange({ status: e.target.value }) })), values.createdBy && (_jsxs(Stack, { gap: "none", children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Created by" }), _jsx(Text, { size: "sm", color: "muted", children: values.createdBy })] })), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.allowGuestParticipation, onChange: (v) => onChange({ allowGuestParticipation: v }), label: "Allow guest participation (no login required)" }), _jsx(Text, { size: "xs", color: "muted", children: "When enabled, unauthenticated visitors can participate in this event (poll vote, survey/feedback response, raffle entry, or wheel spin), identified by a hashed IP address instead of an account. Applies uniformly to whatever entry mechanism this event type uses." })] }), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.isPinned, onChange: (v) => onChange({ isPinned: v }), label: "Pin to the top of Events" }), _jsx(Text, { size: "xs", color: "muted", children: "Pinned events are listed first on the Events page and in the homepage strip, ahead of the usual soonest-first order. A pinned event still has to be Active to appear at all \u2014 pinning does not publish it." })] }), values.type === "sale" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Sale configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Discount %", type: "number", value: values.discountPercent, onChange: (e) => onChange({ discountPercent: e.target.value }), placeholder: "10" }), _jsx(Input, { label: "Banner text (optional)", value: values.saleBannerText, onChange: (e) => onChange({ saleBannerText: e.target.value }), placeholder: "Limited time \u2014 ends Sunday!" })] })] })), values.type === "offer" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Offer configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.couponId, onChange: (id) => onChange({ couponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsx(Input, { label: "Display code", value: values.displayCode, onChange: (e) => onChange({ displayCode: e.target.value }), placeholder: "CHARIZARD25", required: true })] }), _jsx(Input, { label: "Banner text (optional)", value: values.offerBannerText, onChange: (e) => onChange({ offerBannerText: e.target.value }), placeholder: "Use CHARIZARD25 at checkout" })] })), values.type === "poll" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Poll configuration" }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", children: "Options (minimum 2)" }), values.pollOptions.map((opt, idx) => (_jsxs(Row, { gap: "xs", children: [_jsx(Div, { className: "flex-1", children: _jsx(Input, { value: opt.label, onChange: (e) => onChange({ pollOptions: values.pollOptions.map((o) => o.id === opt.id ? { ...o, label: e.target.value } : o) }), placeholder: `Option ${idx + 1}` }) }), values.pollOptions.length > 2 && (_jsx(Button, { variant: "ghost", type: "button", onClick: () => onChange({ pollOptions: values.pollOptions.filter((o) => o.id !== opt.id) }), className: CLS_REMOVE_BTN_PX2, "aria-label": "Remove option", children: "\u00D7" }))] }, opt.id))), _jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: () => onChange({ pollOptions: [...values.pollOptions, { id: `opt${Date.now()}`, label: "" }] }), children: "+ Add option" })] }), _jsx(Select, { label: "Results visibility", value: values.resultsVisibility, options: POLL_VISIBILITY_OPTIONS, onChange: (e) => onChange({ resultsVisibility: e.target.value }) }), _jsxs(Stack, { gap: "sm", children: [_jsx(Toggle, { checked: values.allowMultiSelect, onChange: (v) => onChange({ allowMultiSelect: v }), label: "Allow multi-select" }), _jsx(Toggle, { checked: values.allowComment, onChange: (v) => onChange({ allowComment: v }), label: "Allow comment with vote" })] })] })), values.type === "survey" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Survey configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Max entries per user", type: "number", value: values.maxEntriesPerUser, onChange: (e) => onChange({ maxEntriesPerUser: e.target.value }), placeholder: "1" }), values.hasPointSystem && (_jsx(Input, { label: "Points label", value: values.pointsLabel, onChange: (e) => onChange({ pointsLabel: e.target.value }), placeholder: "Points" }))] }), _jsxs(Stack, { gap: "xs", children: [_jsx(Toggle, { checked: values.requireLogin, onChange: (v) => onChange({ requireLogin: v }), label: "Require login to participate" }), _jsx(Toggle, { checked: values.hasLeaderboard, onChange: (v) => onChange({ hasLeaderboard: v }), label: "Show leaderboard" }), _jsx(Toggle, { checked: values.hasPointSystem, onChange: (v) => onChange({ hasPointSystem: v }), label: "Enable point system" }), _jsx(Toggle, { checked: values.entryReviewRequired, onChange: (v) => onChange({ entryReviewRequired: v }), label: "Require employee review before entry is approved" })] }), _jsx(FormFieldBuilder, { fields: values.surveyFields, setFields: (f) => onChange({ surveyFields: f }) })] })), values.type === "feedback" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Feedback configuration" }), _jsx(Toggle, { checked: values.anonymous, onChange: (v) => onChange({ anonymous: v }), label: "Allow anonymous submissions" }), _jsx(FormFieldBuilder, { fields: values.feedbackFields, setFields: (f) => onChange({ feedbackFields: f }) })] }))] })),
+            render: ({ values, onChange, errors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Event Settings" }), isEdit && (_jsx(Select, { label: "Status", error: errors.status, value: values.status, options: EVENT_STATUS_OPTIONS, onChange: (e) => onChange({ status: e.target.value }) })), values.createdBy && (_jsxs(Stack, { gap: "none", children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Created by" }), _jsx(Text, { size: "sm", color: "muted", children: values.createdBy })] })), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.allowGuestParticipation, onChange: (v) => onChange({ allowGuestParticipation: v }), label: "Allow guest participation (no login required)" }), _jsx(Text, { size: "xs", color: "muted", children: "When enabled, unauthenticated visitors can participate in this event (poll vote, survey/feedback response, raffle entry, or wheel spin), identified by a hashed IP address instead of an account. Applies uniformly to whatever entry mechanism this event type uses." })] }), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.isPinned, onChange: (v) => onChange({ isPinned: v }), label: "Pin to the top of Events" }), _jsx(Text, { size: "xs", color: "muted", children: "Pinned events are listed first on the Events page and in the homepage strip, ahead of the usual soonest-first order. A pinned event still has to be Active to appear at all \u2014 pinning does not publish it." })] }), values.type === "sale" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Sale configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Discount %", error: errors.discountPercent, type: "number", value: values.discountPercent, onChange: (e) => onChange({ discountPercent: e.target.value }), placeholder: "10" }), _jsx(Input, { label: "Banner text (optional)", value: values.saleBannerText, error: errors.saleBannerText, onChange: (e) => onChange({ saleBannerText: e.target.value }), placeholder: "Limited time \u2014 ends Sunday!" })] })] })), values.type === "offer" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Offer configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.couponId, onChange: (id) => onChange({ couponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsx(Input, { label: "Display code", error: errors.displayCode, value: values.displayCode, onChange: (e) => onChange({ displayCode: e.target.value }), placeholder: "CHARIZARD25", required: true })] }), _jsx(Input, { label: "Banner text (optional)", value: values.offerBannerText, error: errors.offerBannerText, onChange: (e) => onChange({ offerBannerText: e.target.value }), placeholder: "Use CHARIZARD25 at checkout" })] })), values.type === "poll" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Poll configuration" }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", children: "Options (minimum 2)" }), values.pollOptions.map((opt, idx) => (_jsxs(Row, { gap: "xs", children: [_jsx(Div, { className: "flex-1", children: _jsx(Input, { value: opt.label, 
+                                                    /* Indexed: a failure on option 2 arrives as `pollOptions.1.label`. */
+                                                    error: errors[`pollOptions.${idx}.label`], onChange: (e) => onChange({ pollOptions: values.pollOptions.map((o) => o.id === opt.id ? { ...o, label: e.target.value } : o) }), placeholder: `Option ${idx + 1}` }) }), values.pollOptions.length > 2 && (_jsx(Button, { variant: "ghost", type: "button", onClick: () => onChange({ pollOptions: values.pollOptions.filter((o) => o.id !== opt.id) }), className: CLS_REMOVE_BTN_PX2, "aria-label": "Remove option", children: "\u00D7" }))] }, opt.id))), _jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: () => onChange({ pollOptions: [...values.pollOptions, { id: `opt${Date.now()}`, label: "" }] }), children: "+ Add option" })] }), _jsx(Select, { label: "Results visibility", error: errors.resultsVisibility, value: values.resultsVisibility, options: POLL_VISIBILITY_OPTIONS, onChange: (e) => onChange({ resultsVisibility: e.target.value }) }), _jsxs(Stack, { gap: "sm", children: [_jsx(Toggle, { checked: values.allowMultiSelect, onChange: (v) => onChange({ allowMultiSelect: v }), label: "Allow multi-select" }), _jsx(Toggle, { checked: values.allowComment, onChange: (v) => onChange({ allowComment: v }), label: "Allow comment with vote" })] })] })), values.type === "survey" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Survey configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Max entries per user", error: errors.maxEntriesPerUser, type: "number", value: values.maxEntriesPerUser, onChange: (e) => onChange({ maxEntriesPerUser: e.target.value }), placeholder: "1" }), values.hasPointSystem && (_jsx(Input, { label: "Points label", error: errors.pointsLabel, value: values.pointsLabel, onChange: (e) => onChange({ pointsLabel: e.target.value }), placeholder: "Points" }))] }), _jsxs(Stack, { gap: "xs", children: [_jsx(Toggle, { checked: values.requireLogin, onChange: (v) => onChange({ requireLogin: v }), label: "Require login to participate" }), _jsx(Toggle, { checked: values.hasLeaderboard, onChange: (v) => onChange({ hasLeaderboard: v }), label: "Show leaderboard" }), _jsx(Toggle, { checked: values.hasPointSystem, onChange: (v) => onChange({ hasPointSystem: v }), label: "Enable point system" }), _jsx(Toggle, { checked: values.entryReviewRequired, onChange: (v) => onChange({ entryReviewRequired: v }), label: "Require employee review before entry is approved" })] }), _jsx(FormFieldBuilder, { fields: values.surveyFields, setFields: (f) => onChange({ surveyFields: f }) })] })), values.type === "feedback" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Feedback configuration" }), _jsx(Toggle, { checked: values.anonymous, onChange: (v) => onChange({ anonymous: v }), label: "Allow anonymous submissions" }), _jsx(FormFieldBuilder, { fields: values.feedbackFields, setFields: (f) => onChange({ feedbackFields: f }) })] }))] })),
         },
         {
             id: "raffle",
             label: "Raffle / Spin",
             fields: ["hasRaffle", "raffleType", "raffleTopN", "rafflePrize", "rafflePrizeCouponId", "rafflePrizeProductIds", "spinPrizes", "spinMaxPerUser", "spinWindowStart", "spinWindowEnd"],
-            render: ({ values, onChange }) => {
+            render: ({ values, onChange, errors }) => {
                 const isRaffleType = values.type === "raffle" || values.type === "spin_wheel";
                 const showRaffleConfig = isRaffleType || values.hasRaffle;
                 const isSpinMode = values.type === "spin_wheel" || values.raffleType === "spin_wheel";
-                return (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Raffle & Spin Wheel" }), !isRaffleType && (_jsx(Toggle, { checked: values.hasRaffle, onChange: (v) => onChange({ hasRaffle: v }), label: "Attach a raffle to this event" })), !isRaffleType && !values.hasRaffle && (_jsx(Text, { size: "sm", color: "muted", children: "Enable the toggle above to attach a raffle draw to this event. Not applicable for this event type by default." })), showRaffleConfig && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Select, { label: "Raffle type", value: values.type === "spin_wheel" ? "spin_wheel" : values.raffleType, options: RAFFLE_TYPE_OPTIONS, onChange: (e) => onChange({ raffleType: e.target.value }), disabled: values.type === "spin_wheel" }), _jsx(Input, { label: "Top N (for top-N raffle types)", type: "number", value: values.raffleTopN, onChange: (e) => onChange({ raffleTopN: e.target.value }), placeholder: "10" })] }), _jsx(Input, { label: "Prize description", value: values.rafflePrize, onChange: (e) => onChange({ rafflePrize: e.target.value }), placeholder: "\u20B92,000 store credit + exclusive Pikachu sticker" }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon for winner (optional)" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.rafflePrizeCouponId, onChange: (id) => onChange({ rafflePrizeCouponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Prize products (optional)" }), _jsx(ProductInlineSelect, { scope: "admin", multiple: true, value: values.rafflePrizeProductIds, onChange: (ids) => onChange({ rafflePrizeProductIds: ids }), placeholder: "Search products to feature as prizes\u2026" }), _jsx(Text, { size: "xs", color: "muted", className: "mt-1", children: "Products shown to winners or displayed as the prize showcase." })] }), isSpinMode && _jsx(SpinPrizesEditor, { values: values, onChange: onChange }), isEdit && (_jsxs(Stack, { gap: "xs", rounded: "lg", padding: "sm", className: CLS_RAFFLE_PANEL, children: [_jsxs(Row, { justify: "between", gap: "sm", children: [_jsx(Text, { size: "sm", weight: "medium", className: CLS_RAFFLE_HEADING, children: raffleWinnerName ? `Winner: ${raffleWinnerName}` : "Raffle not yet triggered" }), _jsx(Button, { type: "button", action: ACTIONS.EVENT["draw-raffle-winner"], size: "sm", onClick: () => triggerRaffleMutation.mutate(), disabled: triggerRaffleMutation.isPending || Boolean(raffleWinnerName), children: triggerRaffleMutation.isPending ? "Triggering…" : raffleWinnerName ? "Already triggered" : "Trigger Raffle Now" })] }), raffleEntryCount !== null && _jsxs(Text, { size: "xs", className: CLS_RAFFLE_BODY, children: ["Pool size: ", raffleEntryCount] }), raffleGithubUrl && _jsxs(Text, { size: "xs", className: `break-all ${CLS_RAFFLE_BODY}`, children: ["Fairness proof: ", raffleGithubUrl] }), triggerMessage && _jsx(Text, { size: "xs", className: CLS_RAFFLE_HEADING, children: triggerMessage })] }))] }))] }));
+                return (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Raffle & Spin Wheel" }), !isRaffleType && (_jsx(Toggle, { checked: values.hasRaffle, onChange: (v) => onChange({ hasRaffle: v }), label: "Attach a raffle to this event" })), !isRaffleType && !values.hasRaffle && (_jsx(Text, { size: "sm", color: "muted", children: "Enable the toggle above to attach a raffle draw to this event. Not applicable for this event type by default." })), showRaffleConfig && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Select, { label: "Raffle type", error: errors.raffleType, value: values.type === "spin_wheel" ? "spin_wheel" : values.raffleType, options: RAFFLE_TYPE_OPTIONS, onChange: (e) => onChange({ raffleType: e.target.value }), disabled: values.type === "spin_wheel" }), _jsx(Input, { label: "Top N (for top-N raffle types)", error: errors.raffleTopN, type: "number", value: values.raffleTopN, onChange: (e) => onChange({ raffleTopN: e.target.value }), placeholder: "10" })] }), _jsx(Input, { label: "Prize description", error: errors.rafflePrize, value: values.rafflePrize, onChange: (e) => onChange({ rafflePrize: e.target.value }), placeholder: "\u20B92,000 store credit + exclusive Pikachu sticker" }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon for winner (optional)" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.rafflePrizeCouponId, onChange: (id) => onChange({ rafflePrizeCouponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Prize products (optional)" }), _jsx(ProductInlineSelect, { scope: "admin", multiple: true, value: values.rafflePrizeProductIds, onChange: (ids) => onChange({ rafflePrizeProductIds: ids }), placeholder: "Search products to feature as prizes\u2026" }), _jsx(Text, { size: "xs", color: "muted", className: "mt-1", children: "Products shown to winners or displayed as the prize showcase." })] }), isSpinMode && _jsx(SpinPrizesEditor, { values: values, onChange: onChange }), isEdit && (_jsxs(Stack, { gap: "xs", rounded: "lg", padding: "sm", className: CLS_RAFFLE_PANEL, children: [_jsxs(Row, { justify: "between", gap: "sm", children: [_jsx(Text, { size: "sm", weight: "medium", className: CLS_RAFFLE_HEADING, children: raffleWinnerName ? `Winner: ${raffleWinnerName}` : "Raffle not yet triggered" }), _jsx(Button, { type: "button", action: ACTIONS.EVENT["draw-raffle-winner"], size: "sm", onClick: () => triggerRaffleMutation.mutate(), disabled: triggerRaffleMutation.isPending || Boolean(raffleWinnerName), children: triggerRaffleMutation.isPending ? "Triggering…" : raffleWinnerName ? "Already triggered" : "Trigger Raffle Now" })] }), raffleEntryCount !== null && _jsxs(Text, { size: "xs", className: CLS_RAFFLE_BODY, children: ["Pool size: ", raffleEntryCount] }), raffleGithubUrl && _jsxs(Text, { size: "xs", className: `break-all ${CLS_RAFFLE_BODY}`, children: ["Fairness proof: ", raffleGithubUrl] }), triggerMessage && _jsx(Text, { size: "xs", className: CLS_RAFFLE_HEADING, children: triggerMessage })] }))] }))] }));
             },
         },
     ];

package/dist/features/faq/components/FAQAccordion.d.ts

@@ -1,5 +1,6 @@
 import React from "react";
 import type { FAQ, FAQCategory } from "../types";
+import { type PublishedValues } from "../../../_internal/shared/content/published-values";
 export interface FAQAccordionProps {
     faqs: FAQ[];
     className?: string;
@@ -8,8 +9,19 @@ export interface FAQAccordionProps {
     labels?: {
         noResults?: string;
     };
+    /**
+     * Phase 9 — resolved published values, for `{{token}}` substitution in
+     * answers. Build them with `resolvePublishedValues(settings?.commissions)`
+     * at the page level and pass them down.
+     *
+     * 🛑 Passed in rather than read here. This component renders on the server
+     * and in the client, and a settings read inside a presentational component
+     * would both make it unusable in half the places it is needed and fire one
+     * read per accordion on a page that has several.
+     */
+    publishedValues?: PublishedValues;
 }
-export declare function FAQAccordion({ faqs, className, renderExpandedFooter, labels, }: FAQAccordionProps): React.JSX.Element;
+export declare function FAQAccordion({ faqs, className, renderExpandedFooter, labels, publishedValues, }: FAQAccordionProps): React.JSX.Element;
 interface FAQCategoryTabsProps {
     categories: FAQCategory[];
     active?: FAQCategory | null;

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

@@ -2,16 +2,41 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
 import { Button, Div, RichText, Row, Span, Tabs, TabsList, TabsTrigger, Text } from "../../../ui/index.js";
+/* Phase 9 — `publishedCopyKey`'s first reader. See the 🛑 at the render site. */
+import { resolvePublishedCopy, resolvePublishedValues, } from "../../../_internal/shared/content/published-values.js";
 import { RecordOwnerQuickActions } from "../../admin/components/RecordOwnerQuickActions.js";
-function FAQAccordionItem({ faq, isOpen, onToggle, renderExpandedFooter, }) {
-    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: faq.answer.text, className: "prose-sm" })) : (_jsx(Text, { className: "whitespace-pre-line", children: faq.answer.text })), _jsx(Row, { justify: "end", className: "mt-3", children: _jsx(RecordOwnerQuickActions, { resource: "FAQ", recordId: faq.id, placement: "detail", recordLabel: faq.question }) }), renderExpandedFooter?.(faq)] }))] }));
+/**
+ * Code-derived values, resolved once at module scope.
+ *
+ * ## 🛑 Why a DEFAULT rather than a required prop
+ *
+ * `resolvePublishedValues()` with no settings argument is PURE over code
+ * constants — the obligation policies, `LANE_CHECKOUT_WINDOW_MS`,
+ * `POINTS_EARN_PERCENT`. It reads no Firestore and touches no settings, so
+ * calling it here costs one object at import and cannot leak anything.
+ *
+ * That matters because there are FOUR mount sites (the FAQ page, the
+ * searchable list, the category highlights section, and this file's own
+ * loop). Requiring the prop would mean threading it through four callers and
+ * their callers — and the one that got missed would render `{{…}}` to a
+ * visitor. A default that always resolves the code-derived numbers, with an
+ * override for the settings-driven money ones, gets every surface right
+ * immediately.
+ *
+ * A caller WITH settings in hand should still pass them: without them the
+ * money values fall back to the schema defaults, which is correct but is not
+ * the admin's current configuration.
+ */
+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)] }))] }));
 }
-export function FAQAccordion({ faqs, className = "", renderExpandedFooter, labels, }) {
+export function FAQAccordion({ faqs, className = "", renderExpandedFooter, labels, publishedValues, }) {
     const [openId, setOpenId] = useState(null);
     if (faqs.length === 0 && labels?.noResults) {
         return (_jsx(Div, { surface: "card", padding: "xl", className: "text-center", children: _jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", children: labels.noResults }) }));
     }
-    return (_jsx(Div, { surface: "card", className: `divide-y divide-neutral-100 divide-[var(--appkit-color-border)] ${className}`, padding: "x-md", children: faqs.map((faq) => (_jsx(FAQAccordionItem, { faq: faq, isOpen: openId === faq.id, onToggle: () => setOpenId(openId === faq.id ? null : faq.id), renderExpandedFooter: renderExpandedFooter }, faq.id))) }));
+    return (_jsx(Div, { surface: "card", className: `divide-y divide-neutral-100 divide-[var(--appkit-color-border)] ${className}`, padding: "x-md", children: faqs.map((faq) => (_jsx(FAQAccordionItem, { faq: faq, isOpen: openId === faq.id, onToggle: () => setOpenId(openId === faq.id ? null : faq.id), renderExpandedFooter: renderExpandedFooter, publishedValues: publishedValues }, faq.id))) }));
 }
 const ALL_TAB_VALUE = "__all__";
 export function FAQCategoryTabs({ categories, active, onSelect, labels = {}, }) {

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

@@ -0,0 +1,112 @@
+/**
+ * Invoicing — the two gapless series (Phase 7, D12)
+ *
+ * ## Why two series and not one field
+ *
+ * **A GST invoice is issued once and must not change.** So a partial
+ * cancellation or refund gets a CREDIT NOTE with its own number referencing
+ * the invoice it adjusts — never a re-issued invoice. That is the whole reason
+ * `creditNoteNumber` is a second series rather than a revision suffix.
+ *
+ * ## 🛑 Gapless means the counter CANNOT be sharded
+ *
+ * Firestore's ~1 write/sec/document ceiling applies to a counter doc, and the
+ * usual answer is to shard it. That answer is unavailable here: a sharded
+ * counter cannot be gapless, which is the entire requirement. At this volume
+ * the ceiling is irrelevant; the note exists so nobody "optimises" it later
+ * and silently breaks the one property an auditor checks.
+ *
+ * ## 🛑 The FINANCIAL YEAR is the riskiest line in the phase
+ *
+ * The series is `LIR/26-27/0001` (decision 21), resetting on 1 April. So the
+ * allocating transaction must key on the FY — if it keys on anything else, two
+ * years share one counter and NEITHER series is gapless. And a number cannot
+ * be withdrawn without leaving a gap, so this is not a mistake that can be
+ * corrected after the fact.
+ */
+/**
+ * ## 🛑 OUTSTANDING — both collections need a PRESERVE entry in the tester tier
+ *
+ * `invoiceCounters` and `invoiceAllocations` are in **no tier**, and
+ * `assertDeletable` THROWS on an unlisted collection name *mid-run* — which
+ * reads as a harness fault rather than a classification gap. That is the exact
+ * latent trip `gatewayOrderClaims` sat on, and these two are worse: a wiped
+ * counter would restart a series at 1 and re-issue numbers that already exist
+ * on real invoices, which is unrecoverable.
+ *
+ * The entry belongs in `tester/scripts/lib/collections.mjs`'s PRESERVE list,
+ * beside `payoutMethods` and `adminAuditLog`. It is not in this change because
+ * **the `tester` submodule is not initialised in this worktree** (`git
+ * submodule status` shows it uninitialised), so the file does not exist here to
+ * edit. Recorded rather than silently skipped.
+ *
+ * 🛑 And they must get **no `SEED_COLLECTION_PURPOSE` entry**:
+ * `audit-seed-purpose` R1 requires that registry to match `COLLECTION_MAP` in
+ * BOTH directions, so a key for a collection the seeder does not write is a
+ * DEAD entry and fails the audit. Neither of these is ever seeded — they are
+ * written only by allocation. The same mistake was made with `refundClaims`
+ * and reverted.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const INVOICE_COUNTER_COLLECTION = "invoiceCounters";
+/** The two independent series. */
+export type InvoiceSeriesKind = "invoice" | "credit_note";
+/**
+ * One counter per (series, financial year).
+ *
+ * The document id IS `${kind}_${fy}` — e.g. `invoice_26-27` — so the
+ * transaction that allocates a number needs no query, and two series in the
+ * same year cannot contend with each other.
+ */
+export interface InvoiceCounterDocument extends BaseDocument {
+    kind: InvoiceSeriesKind;
+    /** `"26-27"` — the FY label that appears in the number itself. */
+    fy: string;
+    /**
+     * The last number ISSUED. The next allocation is `lastNumber + 1`.
+     *
+     * 🛑 Last-issued rather than next-to-issue, deliberately: a counter created
+     * at 0 means "nothing issued yet", which is true and self-evident, whereas a
+     * next-to-issue counter created at 0 would mint `LIR/26-27/0000`.
+     */
+    lastNumber: number;
+    /** When this counter last allocated — for the operator, never read by code. */
+    lastIssuedAt?: Date;
+}
+/**
+ * A record of every number allocated, keyed on what it was allocated FOR.
+ *
+ * ## 🛑 This is the idempotency claim, and it is why a number cannot be issued
+ * twice for one order
+ *
+ * `onOrderStatusChange` can fire more than once, and **two numbers for one
+ * order is the single unrecoverable failure in this phase** — the spare number
+ * is a permanent gap that cannot be explained to an auditor and cannot be
+ * reclaimed.
+ *
+ * So allocation is a `.create()` on `invoiceAllocations/{subjectId}` INSIDE
+ * the same transaction that bumps the counter. `.create()` fails if the
+ * document exists, which makes "already allocated" a transaction-level fact
+ * rather than a read-then-write race. It is the same primitive the refund
+ * claim, the gateway-event inbox and the gateway-order claim all use.
+ */
+export declare const INVOICE_ALLOCATION_COLLECTION = "invoiceAllocations";
+export interface InvoiceAllocationDocument extends BaseDocument {
+    kind: InvoiceSeriesKind;
+    /**
+     * What this number was issued for.
+     *
+     * 🛑 For an invoice this is the ORDER id, so one order can only ever hold
+     * one invoice number. For a credit note it is `${orderId}_${refundId}`,
+     * because an order can legitimately have several credit notes — one per
+     * refund event — and keying a credit note on the order alone would refuse
+     * the second one.
+     */
+    subjectId: string;
+    orderId: string;
+    /** The formatted number, e.g. `LIR/26-27/0001`. */
+    number: string;
+    fy: string;
+    sequence: number;
+    issuedAt: Date;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Invoicing — the two gapless series (Phase 7, D12)
+ *
+ * ## Why two series and not one field
+ *
+ * **A GST invoice is issued once and must not change.** So a partial
+ * cancellation or refund gets a CREDIT NOTE with its own number referencing
+ * the invoice it adjusts — never a re-issued invoice. That is the whole reason
+ * `creditNoteNumber` is a second series rather than a revision suffix.
+ *
+ * ## 🛑 Gapless means the counter CANNOT be sharded
+ *
+ * Firestore's ~1 write/sec/document ceiling applies to a counter doc, and the
+ * usual answer is to shard it. That answer is unavailable here: a sharded
+ * counter cannot be gapless, which is the entire requirement. At this volume
+ * the ceiling is irrelevant; the note exists so nobody "optimises" it later
+ * and silently breaks the one property an auditor checks.
+ *
+ * ## 🛑 The FINANCIAL YEAR is the riskiest line in the phase
+ *
+ * The series is `LIR/26-27/0001` (decision 21), resetting on 1 April. So the
+ * allocating transaction must key on the FY — if it keys on anything else, two
+ * years share one counter and NEITHER series is gapless. And a number cannot
+ * be withdrawn without leaving a gap, so this is not a mistake that can be
+ * corrected after the fact.
+ */
+export const INVOICE_COUNTER_COLLECTION = "invoiceCounters";
+/**
+ * A record of every number allocated, keyed on what it was allocated FOR.
+ *
+ * ## 🛑 This is the idempotency claim, and it is why a number cannot be issued
+ * twice for one order
+ *
+ * `onOrderStatusChange` can fire more than once, and **two numbers for one
+ * order is the single unrecoverable failure in this phase** — the spare number
+ * is a permanent gap that cannot be explained to an auditor and cannot be
+ * reclaimed.
+ *
+ * So allocation is a `.create()` on `invoiceAllocations/{subjectId}` INSIDE
+ * the same transaction that bumps the counter. `.create()` fails if the
+ * document exists, which makes "already allocated" a transaction-level fact
+ * rather than a read-then-write race. It is the same primitive the refund
+ * claim, the gateway-event inbox and the gateway-order claim all use.
+ */
+export const INVOICE_ALLOCATION_COLLECTION = "invoiceAllocations";

package/dist/features/invoicing/utils/financial-year.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The Indian financial year, and the series format built on it.
+ *
+ * ## 🛑 1 April, and getting the boundary wrong is unrecoverable
+ *
+ * The FY segment is what makes the reset safe: a counter keyed on the year
+ * resets by construction, because 1 April produces a new key. But it also
+ * means a boundary error is permanent — a number issued under the wrong FY
+ * leaves a gap in one year's series and an extra in the other, and a number
+ * cannot be withdrawn.
+ *
+ * So the month test is `>= 3` on a ZERO-BASED month (April is 3, not 4). That
+ * single off-by-one is the whole risk, and it is why this is a named function
+ * with its reasoning attached rather than an inline expression at the call
+ * site.
+ */
+/**
+ * `"26-27"` for any date from 2026-04-01 to 2027-03-31.
+ *
+ * Two-digit years, matching decision 21's `LIR/26-27/0001`. The full number is
+ * 14 characters, inside the statutory 16, and uses only `-` and `/` as
+ * separators.
+ */
+export declare function financialYearLabel(at: Date): string;
+/**
+ * Prefixes, per decision 21.
+ *
+ * 🛑 Distinct prefixes rather than one with a suffix, so the two series are
+ * distinguishable at a glance in a bank statement, a spreadsheet and a GSTR-1
+ * row — and so a text search for one can never match the other.
+ */
+export declare const INVOICE_PREFIX = "LIR";
+export declare const CREDIT_NOTE_PREFIX = "LIRCN";
+/**
+ * `LIR/26-27/0001`.
+ *
+ * Zero-padded to four digits, which covers 9,999 documents per series per
+ * year. 🛑 Overflow does NOT wrap or throw: `padStart` is a floor, not a
+ * ceiling, so number 10,000 renders as `10000` and the series stays gapless
+ * and sortable-by-sequence. Width is cosmetic; gaplessness is not, and the
+ * failure mode of a throw here would be a paid order that cannot be invoiced.
+ */
+export declare function formatSeriesNumber(prefix: string, fy: string, sequence: number): string;

package/dist/features/invoicing/utils/financial-year.js

@@ -0,0 +1,53 @@
+/**
+ * The Indian financial year, and the series format built on it.
+ *
+ * ## 🛑 1 April, and getting the boundary wrong is unrecoverable
+ *
+ * The FY segment is what makes the reset safe: a counter keyed on the year
+ * resets by construction, because 1 April produces a new key. But it also
+ * means a boundary error is permanent — a number issued under the wrong FY
+ * leaves a gap in one year's series and an extra in the other, and a number
+ * cannot be withdrawn.
+ *
+ * So the month test is `>= 3` on a ZERO-BASED month (April is 3, not 4). That
+ * single off-by-one is the whole risk, and it is why this is a named function
+ * with its reasoning attached rather than an inline expression at the call
+ * site.
+ */
+/**
+ * `"26-27"` for any date from 2026-04-01 to 2027-03-31.
+ *
+ * Two-digit years, matching decision 21's `LIR/26-27/0001`. The full number is
+ * 14 characters, inside the statutory 16, and uses only `-` and `/` as
+ * separators.
+ */
+export function financialYearLabel(at) {
+    const year = at.getFullYear();
+    // 🛑 ZERO-BASED. `getMonth()` returns 3 for April, so `>= 3` is "April or
+    // later" and `< 3` is "January to March", which belongs to the FY that
+    // STARTED in the previous calendar year.
+    const startYear = at.getMonth() >= 3 ? year : year - 1;
+    const endYear = startYear + 1;
+    return `${String(startYear % 100).padStart(2, "0")}-${String(endYear % 100).padStart(2, "0")}`;
+}
+/**
+ * Prefixes, per decision 21.
+ *
+ * 🛑 Distinct prefixes rather than one with a suffix, so the two series are
+ * distinguishable at a glance in a bank statement, a spreadsheet and a GSTR-1
+ * row — and so a text search for one can never match the other.
+ */
+export const INVOICE_PREFIX = "LIR";
+export const CREDIT_NOTE_PREFIX = "LIRCN";
+/**
+ * `LIR/26-27/0001`.
+ *
+ * Zero-padded to four digits, which covers 9,999 documents per series per
+ * year. 🛑 Overflow does NOT wrap or throw: `padStart` is a floor, not a
+ * ceiling, so number 10,000 renders as `10000` and the series stays gapless
+ * and sortable-by-sequence. Width is cosmetic; gaplessness is not, and the
+ * failure mode of a throw here would be a paid order that cannot be invoiced.
+ */
+export function formatSeriesNumber(prefix, fy, sequence) {
+    return `${prefix}/${fy}/${String(sequence).padStart(4, "0")}`;
+}

package/dist/features/jobs/actions/enqueue-job.js

@@ -15,7 +15,7 @@
 import { normalizeError } from "../../../errors/normalize.js";
 import { serverLogger } from "../../../monitoring/index.js";
 import { jobsRepository } from "../../../repositories/index.js";
-import { JobStatusValues } from "../schemas/firestore.js";
+import { JOB_MAX_ATTEMPTS, JobStatusValues } from "../schemas/firestore.js";
 import { getAdminAuth, getAdminRealtimeDb } from "../../../providers/db-firebase/index.js";
 import { RTDB_PATHS } from "../../../providers/db-firebase/rtdb-paths.js";
 export async function enqueueJob(input) {
@@ -24,6 +24,23 @@ export async function enqueueJob(input) {
         status: JobStatusValues.PENDING,
         payload: input.payload,
         requestedBy: input.requestedBy,
+        /*
+         * Phase 8 — attempt 1 of N, stated rather than implied.
+         *
+         * `attempt` defaults to 1 everywhere it is read, so this write is not
+         * strictly required — but an explicit 1 is what makes an ENQUEUED job
+         * distinguishable from a pre-Phase-8 row at a glance, and it is what a
+         * reader of the collection needs when three documents share a
+         * `parentJobId`.
+         *
+         * 🛑 `nextAttemptAt` is deliberately ABSENT. It is the retry sweep's query
+         * field, and the create trigger skips any job carrying a future one — so
+         * setting it here (even to `now`) would put every first attempt at the
+         * mercy of a 5-minute sweep instead of running immediately, turning a
+         * synchronous-feeling admin action into one that appears to hang.
+         */
+        attempt: 1,
+        maxAttempts: JOB_MAX_ATTEMPTS,
     });
     try {
         await getAdminRealtimeDb()