@mohasinac/appkit 4.70.0 → 4.71.2

package/dist/constants/storage-keys.js

@@ -0,0 +1,131 @@
+/**
+ * Browser-storage and postMessage keys — one namespace, configurable.
+ *
+ * ## Why this exists
+ *
+ * Seven call sites hardcoded a `letitrip`-prefixed key:
+ *
+ *   localStorage  "letitrip:section-state" · "letitrip:last-category"
+ *                 "letitrip:announcement-dismissed" · "letitrip_oauth_redirect"
+ *                 "letitrip_search_type"
+ *   postMessage   "letitrip_auth_close"
+ *
+ * For the app that shipped them that is harmless. For a LIBRARY it is not:
+ * every consumer inherits one marketplace's namespace, two appkit apps on the
+ * same origin collide, and the brand is baked into data the user's browser
+ * keeps. Tier AK's whole premise is that appkit should not know whose app it
+ * is in.
+ *
+ * ## 🛑 The prefix is read at CALL TIME, not at module load
+ *
+ * `storageKey()` is a function and the keys below are getters. A consumer sets
+ * the namespace from its own bootstrap, which runs after this module is
+ * evaluated — so a `const KEY = PREFIX + ":x"` captured at import time would
+ * freeze the default and silently ignore the configuration. That is the same
+ * trap as a mirror field (Root Cause #42): two things that must agree, where
+ * only one is ever written.
+ *
+ * ## 🛑 Changing the namespace ORPHANS existing values
+ *
+ * These keys are how a returning visitor's dismissed banner and collapsed
+ * sections are remembered. Renaming the prefix does not migrate them — the old
+ * entries simply stop being read. That is acceptable for UI state and would NOT
+ * be for anything load-bearing, which is why nothing load-bearing belongs here:
+ * the auth session is an HTTP-only cookie, not a storage key.
+ *
+ * ## The separator is deliberately NOT normalised
+ *
+ * Five keys use `:` and three use `_`. They are kept exactly as they were,
+ * because normalising them is a silent data migration for every existing
+ * visitor in exchange for tidiness. New keys should use `:`.
+ */
+/**
+ * Default namespace.
+ *
+ * Deliberately NOT "letitrip" — a library's default must not name one
+ * consumer. `"appkit"` is what an unconfigured install gets, which is both
+ * neutral and obviously-a-default when seen in devtools.
+ */
+const DEFAULT_STORAGE_NAMESPACE = "appkit";
+let namespace = DEFAULT_STORAGE_NAMESPACE;
+/**
+ * Set the prefix every appkit storage key carries. Call once, from the
+ * consumer's client bootstrap, before any UI mounts.
+ *
+ * Idempotent and last-call-wins; there is no unset, because a namespace that
+ * changes mid-session would strand whatever was written under the previous one.
+ */
+export function setStorageNamespace(value) {
+    const trimmed = value.trim();
+    if (trimmed)
+        namespace = trimmed;
+}
+/** The active namespace. Exported for diagnostics, not for building keys. */
+export function getStorageNamespace() {
+    return namespace;
+}
+/**
+ * Build a namespaced key.
+ *
+ * @param suffix the part after the separator, e.g. `"last-category"`
+ * @param separator `":"` for new keys; `"_"` only where an existing key used it
+ */
+export function storageKey(suffix, separator = ":") {
+    return `${namespace}${separator}${suffix}`;
+}
+/**
+ * The keys appkit itself owns.
+ *
+ * Getters, not constants — see the call-time note above. Each records the
+ * literal it replaced so the migration is auditable and a reader can tell at a
+ * glance which separator is historical rather than chosen.
+ */
+export const STORAGE_KEYS = {
+    /** Collapsed account-page sections. Was `"letitrip:section-state"`. */
+    get sectionState() {
+        return storageKey("section-state");
+    },
+    /** Per-user hidden dashboard hub cards (Phase 4A, overhaul brief). */
+    get hiddenHubCards() {
+        return storageKey("hidden-hub-cards");
+    },
+    /** Per-user recently-visited/used dashboard-landing cards (Phase 9, overhaul brief). */
+    get recentlyVisited() {
+        return storageKey("recently-visited");
+    },
+    /** Per-user, user-curated (uncapped) dashboard-landing cards (Phase 9-ii, overhaul brief). */
+    get savedCards() {
+        return storageKey("saved-cards");
+    },
+    /** Last category visited, for the contextual trail. Was `"letitrip:last-category"`. */
+    get lastCategory() {
+        return storageKey("last-category");
+    },
+    /** Announcement bar dismissal. Was `"letitrip:announcement-dismissed"`. */
+    get announcementDismissed() {
+        return storageKey("announcement-dismissed");
+    },
+    /** OAuth return URL across the popup round-trip. Was `"letitrip_oauth_redirect"`. */
+    get oauthRedirect() {
+        return storageKey("oauth_redirect", "_");
+    },
+    /** Remembered search-type tab. Was `"letitrip_search_type"`. */
+    get searchType() {
+        return storageKey("search_type", "_");
+    },
+};
+/**
+ * postMessage `type` values.
+ *
+ * 🛑 Namespaced for the same reason, and with a sharper edge: a `message`
+ * listener receives events from ANY window that can reach it, so an
+ * unnamespaced type is both a collision and an input-validation question. The
+ * listeners that read this must keep checking `event.origin` regardless — a
+ * namespace is not an authentication mechanism.
+ */
+export const MESSAGE_TYPES = {
+    /** Auth popup signalling it is done. Was `"letitrip_auth_close"`. */
+    get authClose() {
+        return storageKey("auth_close", "_");
+    },
+};

package/dist/constants/table-keys.d.ts

@@ -31,7 +31,7 @@ export declare const TABLE_KEYS: {
     /**
      * Superseded by AVAILABILITY. Retained ONLY so `readAvailability()` can map
      * bookmarked `?showSold=true` URLs onto `availability=all`, and because the
-     * seller auction/prize-draw dashboards still read them during migration.
+     * seller collector drop/prize-draw dashboards still read them during migration.
      * Never write these from new code.
      */
     readonly SHOW_SOLD: "showSold";
@@ -39,7 +39,7 @@ export declare const TABLE_KEYS: {
     readonly SHOW_CLOSED: "showClosed";
     readonly FEATURED: "featured";
     readonly IS_FEATURED: "isFeatured";
-    readonly AUCTION_ID: "auctionId";
+    readonly COLLECTOR_DROP_ID: "collectorDropId";
     readonly BIDDER_ID: "bidderId";
     readonly STORE_NAME: "storeName";
     readonly LISTING_TYPE: "listingType";
@@ -58,6 +58,7 @@ export declare const TABLE_KEYS: {
     readonly IS_PART_OF_BUNDLE: "isPartOfBundle";
     readonly SUBLISTING_CATEGORY: "sublistingCategory";
     readonly FEATURES: "features";
+    readonly IS_ON_SALE: "isOnSale";
     readonly CITY: "city";
     readonly ACCEPTS_SHIPPING: "acceptsShipping";
     readonly NEGOTIABLE: "negotiable";

package/dist/constants/table-keys.js

@@ -31,7 +31,7 @@ export const TABLE_KEYS = {
     /**
      * Superseded by AVAILABILITY. Retained ONLY so `readAvailability()` can map
      * bookmarked `?showSold=true` URLs onto `availability=all`, and because the
-     * seller auction/prize-draw dashboards still read them during migration.
+     * seller collector drop/prize-draw dashboards still read them during migration.
      * Never write these from new code.
      */
     SHOW_SOLD: "showSold",
@@ -39,7 +39,7 @@ export const TABLE_KEYS = {
     SHOW_CLOSED: "showClosed",
     FEATURED: "featured",
     IS_FEATURED: "isFeatured",
-    AUCTION_ID: "auctionId",
+    COLLECTOR_DROP_ID: "collectorDropId",
     BIDDER_ID: "bidderId",
     STORE_NAME: "storeName",
     LISTING_TYPE: "listingType",
@@ -58,6 +58,7 @@ export const TABLE_KEYS = {
     IS_PART_OF_BUNDLE: "isPartOfBundle",
     SUBLISTING_CATEGORY: "sublistingCategory",
     FEATURES: "features",
+    IS_ON_SALE: "isOnSale",
     // Classified-specific
     CITY: "city",
     ACCEPTS_SHIPPING: "acceptsShipping",

package/dist/contracts/ai.d.ts

@@ -0,0 +1,183 @@
+import type { JsonObject } from "../schemas/types";
+/**
+ * The assistant's model contract — one provider per vendor, chosen per job.
+ *
+ * Follows the NEWER appkit provider convention: an **abstract class**, as
+ * `IPaymentProvider` / `IShippingProvider` / `ITaxProvider` are, so every
+ * implementation extends one shared base and `tsc` enumerates what it owes.
+ * (The older `IEmailProvider` / `IStorageProvider` are plain interfaces;
+ * `PROVIDERS.md`'s blanket "contracts are abstract classes" is over-general and
+ * describes the deliberate ones.)
+ *
+ * ## 🛑 Why the provider layer exists at all
+ *
+ * Measured 2026-10-29: **two of five** obvious free providers died within three
+ * months — GitHub Models retired 2026-07-30, Cerebras dropped its free tier
+ * 2026-07-16. A vendor-agnostic seam is not architectural taste here; it is the
+ * observed failure rate.
+ *
+ * And it is a seam with a reader from day one (`audit-provider-registry-readers`
+ * exists because Tier AK shipped six that had none): the router below picks
+ * between providers per job, so the abstraction is load-bearing immediately.
+ *
+ * ## Moved here 2026-11 (Phase 2E, overhaul brief)
+ *
+ * Was `_internal/shared/features/assistant/types.ts` — the only
+ * assistant-relevant contract living outside `contracts/`, where every other
+ * provider interface (payment, shipping, tax, email, search, storage, …)
+ * already lives. `providers/ai-groq` is unchanged; only this declaration and
+ * `getAssistantProviders()` in `actions.ts` (now resolving `getProviders().ai`
+ * before falling back to Groq) moved. The request/response/PII vocabulary
+ * below (`Redacted`, `AssistantJob`, `PiiClass`, `ModelTurnRequest`, …) moves
+ * with the interface rather than staying behind, same as `TaxComponent`/
+ * `TaxBreakdown`/`TaxJurisdiction` bundle with `ITaxProvider` in `tax.ts` —
+ * a contract owns its full input/output vocabulary, not just the bare class.
+ *
+ * @tag domain:assistant
+ * @tag layer:contract
+ * @tag access:server
+ */
+/**
+ * A text payload that has passed the redaction layer.
+ *
+ * ## 🛑 This brand is the ENTIRE PII mechanism, and it is nominal on purpose
+ *
+ * The rule from the plan is "a request reaches a training-tier provider only if
+ * it carries a `nonPii` assertion that **only the redaction layer can set** —
+ * default deny". A boolean flag cannot express that: any caller can pass
+ * `true`, and the one that does will be the one in a hurry.
+ *
+ * So `Redacted<T>` is a **nominal brand** with a private declared symbol. It is
+ * erased at runtime and assignable from nothing — the only way to obtain one is
+ * `redact()` in `../redaction`, which is the single module that owns the
+ * scrubbing. A provider whose `trainsOnInput` is true accepts `Redacted<string>`
+ * and nothing else, so sending raw user text to it is a **compile error**, not a
+ * policy someone has to remember.
+ *
+ * Same technique as `appkit/src/security/encrypted.ts`'s `Encrypted<T>`, and the
+ * same caveat applies: it is erased at runtime, so ciphertext, a redacted
+ * string and a real name are all `string` once compiled. The brand buys you the
+ * compiler, not a runtime guarantee — which is why the plan ALSO requires an
+ * adversarial payload grep in verification rather than trusting this alone.
+ */
+declare const REDACTED_BRAND: unique symbol;
+export type Redacted<T extends string = string> = T & {
+    readonly [REDACTED_BRAND]: "redacted";
+};
+/** What the model is being asked to do. Drives routing and the PII gate. */
+export type AssistantJob = 
+/** Classify intent, pick a tool, extract slots. Small and fast. */
+"classify"
+/** Answer the user, with tool calling. The main turn. */
+ | "answer"
+/** Second opinion on money/policy — must resolve to a DIFFERENT vendor. */
+ | "second-opinion"
+/** Detect prompt injection in untrusted input. */
+ | "guard";
+/**
+ * How sensitive the payload is. The router refuses a training-tier provider for
+ * anything but `none`.
+ */
+export type PiiClass = 
+/** Public catalogue/FAQ text. Safe for any provider. */
+"none"
+/** Has been through `redact()`. Carries `Redacted<string>`. */
+ | "redacted"
+/** Contains handles only, never raw identifiers. */
+ | "handle-only";
+export interface ToolSchema {
+    name: string;
+    description: string;
+    /** JSON Schema for the arguments. Derived from the tool's Zod input schema. */
+    parameters: JsonObject;
+}
+export interface ModelToolCall {
+    /**
+     * 🛑 The provider's OWN call id, echoed back verbatim on the matching
+     * `role: "tool"` message.
+     *
+     * This field was missing until the first live tool round, and its absence
+     * was not a cosmetic gap: a tool result must reference the exact id the
+     * model issued, and the assistant turn that requested the tools must carry
+     * its `tool_calls` alongside. Without both, the follow-up request is a
+     * transcript the model cannot render — Groq fails it at the encoder with
+     * `HarmonyError: Tools should have a name!`, which names neither the real
+     * cause nor the field at fault.
+     *
+     * Substituting the tool NAME here compiles, looks plausible, and breaks
+     * every multi-round turn.
+     */
+    id: string;
+    name: string;
+    /** Raw JSON string as the model emitted it — parse and VALIDATE, never trust. */
+    argumentsJson: string;
+}
+export interface ModelTurnRequest {
+    job: AssistantJob;
+    piiClass: PiiClass;
+    /**
+     * The conversation so far.
+     *
+     * 🛑 `Redacted<string>` when `piiClass !== "none"`. See the brand above: this
+     * is what makes an unredacted send fail to compile rather than fail in
+     * production.
+     */
+    messages: ReadonlyArray<{
+        role: "system" | "user" | "assistant" | "tool";
+        content: string | Redacted<string>;
+        /** Set on `role: "tool"` — the `ModelToolCall.id` this result answers. */
+        toolCallId?: string;
+        /**
+         * Set on `role: "assistant"` when that turn REQUESTED tools.
+         *
+         * 🛑 Required for a multi-round transcript to render at all: a
+         * `role: "tool"` message is only meaningful after the assistant message
+         * that asked for it, carrying the matching ids. Omitting these while
+         * still sending the tool results is what produced Groq's
+         * `HarmonyError: Tools should have a name!` on round two.
+         */
+        toolCalls?: readonly ModelToolCall[];
+    }>;
+    tools?: readonly ToolSchema[];
+    maxOutputTokens?: number;
+}
+export interface ModelTurnResult {
+    /** Prose for the user. Empty when the model chose to call a tool instead. */
+    text: string;
+    toolCalls: readonly ModelToolCall[];
+    /**
+     * Why the model stopped. `"tool_calls"` means act on `toolCalls`;
+     * `"length"` means the answer was TRUNCATED and must not be presented as
+     * complete.
+     */
+    finishReason: "stop" | "tool_calls" | "length" | "filtered" | "error";
+    /** For the budget. Counts TOKENS, not calls — a 100k context is not one unit. */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** Which model actually served it, for the provenance record. */
+    modelId: string;
+}
+export declare abstract class IAssistantModelProvider {
+    /** Stable id, e.g. `"groq"`. */
+    abstract readonly id: string;
+    /**
+     * 🛑 Does this vendor train on inputs by contract?
+     *
+     * Measured 2026-10-29: Gemini's free tier **does**; Groq's terms forbid
+     * training on free *and* paid, retain nothing by default, and expose a
+     * zero-retention toggle. India has no EEA/UK carve-out, so there is no
+     * regional exemption to lean on.
+     *
+     * `true` here is what makes the router refuse anything but `piiClass: "none"`.
+     * It is a property of the CONTRACT, not of a setting — do not make it
+     * configurable, because a toggle that downgrades a privacy guarantee is a
+     * toggle someone will flip to make an error go away.
+     */
+    abstract readonly trainsOnInput: boolean;
+    /** Model ids this provider can serve, per job. Read from config, never hardcoded. */
+    abstract modelFor(job: AssistantJob): string | undefined;
+    abstract turn(request: ModelTurnRequest): Promise<ModelTurnResult>;
+}
+export {};

package/dist/contracts/ai.js

@@ -0,0 +1,2 @@
+export class IAssistantModelProvider {
+}

package/dist/contracts/auth.d.ts

@@ -2,8 +2,23 @@ import type { JsonValue } from "../schemas/types";
 export interface AuthPayload {
     uid: string;
     email: string | null;
-    /** Application-level role string, e.g. "admin" | "seller" | "user" */
+    /**
+     * Legacy scalar — the HIGHEST-RANKED role this user holds.
+     *
+     * 🛑 Not the authority. A user holds a SET (`roles` below); deciding access
+     * from this field is what silently locked a multi-role admin out of
+     * `/admin` (reviewer R1-F5). Read `roles`.
+     */
     role: string;
+    /**
+     * THE role authority — every role this user holds, from the token claims.
+     *
+     * Optional because a session cookie minted before the role-set work carries
+     * only `role`; consumers must go through `rolesOf()`, which falls back.
+     */
+    roles?: string[];
+    /** Display label only. Never an authorization input. */
+    primaryRole?: string;
     emailVerified: boolean;
     /** Display name from the auth provider (Google "name" claim) */
     name?: string | null;

package/dist/contracts/client-live-edit.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Client-side live-edit contract (Phase 3, overhaul brief).
+ *
+ * `<LiveEditableRegion>` is a client component — its save has to happen from
+ * the browser, so this is a SEPARATE registry from `contracts/registry.ts`'s
+ * `ProviderRegistry`, matching `IClientAuthProvider`/`IClientSessionAdapter`/
+ * `IClientRealtimeProvider`: those are registered via
+ * `src/lib/client-providers-init.ts` in the consumer, a "use client" module
+ * that runs in the browser bundle, never in `providers.config.ts` (which is
+ * server-only — it imports firebase-admin). Putting this on the server
+ * registry would mean `getProviders().liveEdit` in a browser bundle always
+ * reads a DIFFERENT module instance's `_registry`, which is never the one
+ * `providers.config.ts` populated — the same dual-instance trap Root Cause
+ * #14/#19 describes for the Firebase SDK itself.
+ */
+export interface LiveEditSaveRequest {
+    /** What kind of document this is — e.g. `"faq"`. The provider's own vocabulary. */
+    contentType: string;
+    id: string;
+    /** Which field on the document, e.g. `"answer"`. */
+    field: string;
+    value: string;
+}
+export interface IClientLiveEditProvider {
+    save(request: LiveEditSaveRequest): Promise<void>;
+}
+export declare function registerClientLiveEditProvider(provider: IClientLiveEditProvider): void;
+/** `null` means no provider registered — `<LiveEditableRegion>` renders a disabled affordance rather than a dead one. */
+export declare function getClientLiveEditProvider(): IClientLiveEditProvider | null;

package/dist/contracts/client-live-edit.js

@@ -0,0 +1,23 @@
+/**
+ * Client-side live-edit contract (Phase 3, overhaul brief).
+ *
+ * `<LiveEditableRegion>` is a client component — its save has to happen from
+ * the browser, so this is a SEPARATE registry from `contracts/registry.ts`'s
+ * `ProviderRegistry`, matching `IClientAuthProvider`/`IClientSessionAdapter`/
+ * `IClientRealtimeProvider`: those are registered via
+ * `src/lib/client-providers-init.ts` in the consumer, a "use client" module
+ * that runs in the browser bundle, never in `providers.config.ts` (which is
+ * server-only — it imports firebase-admin). Putting this on the server
+ * registry would mean `getProviders().liveEdit` in a browser bundle always
+ * reads a DIFFERENT module instance's `_registry`, which is never the one
+ * `providers.config.ts` populated — the same dual-instance trap Root Cause
+ * #14/#19 describes for the Firebase SDK itself.
+ */
+let _provider = null;
+export function registerClientLiveEditProvider(provider) {
+    _provider = provider;
+}
+/** `null` means no provider registered — `<LiveEditableRegion>` renders a disabled affordance rather than a dead one. */
+export function getClientLiveEditProvider() {
+    return _provider;
+}

package/dist/contracts/feature.d.ts

@@ -46,7 +46,7 @@ export interface FeatureManifest {
  * export default {
  * auth: true,
  * events: true,
- * auctions: false,
+ * collector drops: false,
  * } satisfies FeaturesConfig;
  * ```
  */

package/dist/contracts/index.d.ts

@@ -2,7 +2,7 @@ export type { WhereOp, SieveQuery, PagedResult, IReadRepository, IWriteRepositor
 export type { AuthPayload, AuthUser, CreateUserInput, IAuthProvider, ISessionProvider, } from "./auth";
 export type { EmailAttachment, EmailOptions, EmailResult, IEmailProvider, } from "./email";
 export type { UploadOptions, StorageFile, IStorageProvider } from "./storage";
-export type { PaymentOrder, PaymentCapture, Refund, Dispute, GatewayPaymentRecord, } from "./payment";
+export type { CheckoutIntentMetadata, PaymentOrder, PaymentCapture, Refund, Dispute, GatewayPaymentRecord, SettlementVendorInput, SettlementVendorOutcome, SettlementVendorResult, SplitInstruction, } from "./payment";
 export { IPaymentProvider } from "./payment";
 export type { ShippingAddress, CreateShipmentInput, Shipment, TrackingEvent, TrackingInfo, ServiceabilityResult, WalletBalance, } from "./shipping";
 export { IShippingProvider } from "./shipping";