@glidevvr/storage-payload-error-logger-pkg 0.1.0

package/dist/types-BLz-TUBl.d.ts

@@ -0,0 +1,198 @@
+type Severity = "error" | "warning" | "info";
+type Source = "payload" | "theme" | "unit-table" | "reservation-app" | "rental-app" | "login";
+type Repo = "gli-payload-multitenant" | "storage-theme-payload" | "unit-table" | "reservation-app" | "rental-app" | "npm-golocal-cloud-wrapper" | "golocal-cloud-wrapper";
+/**
+ * Closed enum of failure-classification codes.
+ *
+ * Splits into two groups:
+ *   1. The 15 SE `errorTag` values shared with `@glidevvr/se-components` —
+ *      keep these in lockstep with that library.
+ *   2. Internal codes for failures that aren't an SE-API call (silent empty
+ *      results, build/scraper/hook errors, uncaught exceptions, etc.).
+ *
+ * Adding a new value here is intentional. If the failure mode you're logging
+ * doesn't fit any value, either add one to this list or use
+ * `"unhandled_exception"` (the deliberate "we don't know" bucket).
+ */
+type Reason = "unit_not_found" | "unit_not_available" | "unit_unavailable" | "facility_not_found" | "invalid_tenant_credentials" | "unauthorized" | "session_expired" | "tenant_not_found" | "reservation_not_found" | "ledger_not_found" | "promotion_not_found" | "payment_failed" | "payment_declined" | "invalid_payment_option" | "validation_error" | "unit_list_empty" | "expected_data_missing" | "cache_stale" | "build_failure" | "hook_error" | "scraper_failure" | "data_integrity" | "unhandled_exception" | "network_timeout";
+interface InitLoggerConfig {
+    /** Absolute URL to the Payload endpoint (e.g. https://payloadstorage.golocaldev.com/cms/api/log-error). */
+    endpoint: string;
+    /** Repo identifier — stamped on every event. */
+    repo: Repo;
+    /** Build identifier (git SHA / build ID) — stamped on every event. */
+    release?: string;
+    /** reCAPTCHA v3 site key (browser-only). If absent, browser-side logging is disabled. */
+    recaptchaSiteKey?: string;
+    /** reCAPTCHA action name; defaults to "log_error". */
+    recaptchaAction?: string;
+    /** Default source for events that don't pass an explicit source. */
+    defaultSource?: Source;
+}
+/**
+ * One line item in `LogContext.charges` / `LogContext.recurringFees`.
+ *
+ * Sub-keys are allowlisted: `id` / `name` / `amount` / `cycle`. Anything else
+ * (memo, note, internal_comment, etc.) is stripped by the server-side
+ * `sanitizeIssueEventContext` hook before persistence.
+ */
+interface LogChargeLine {
+    id?: string;
+    name?: string;
+    amount?: number;
+    /** Only meaningful on `recurringFees`, e.g. "monthly". */
+    cycle?: string;
+}
+/**
+ * Closed allowlist for log context fields.
+ *
+ * **Why this is a closed type (no index signature).** The PII contract for
+ * this logger is "never accept user-input data into the pipeline in the first
+ * place" — not "scrub it after". A closed type makes TypeScript reject unknown
+ * keys at every call site, so card numbers, names, emails, addresses, etc.
+ * cannot accidentally land in an event's `context`.
+ *
+ * Naming convention:
+ *   - `se*` prefix → identifier from the SE API (matches SE's wire term)
+ *   - `vendor*` prefix → identifier from the underlying property-management
+ *     system (SiteLink / StorEdge / DoorSwap)
+ *   - everything else → user-facing terms shared with the admin UI
+ *     (e.g. `organizationId` matches the "Organization" label used in CMS)
+ *
+ * If a new context field is genuinely needed, add it here intentionally and
+ * confirm it carries no PII. The server has a defense-in-depth filter
+ * (`sanitizeIssueEventContext`) that drops unknown keys before persistence.
+ */
+interface LogContext {
+    /** Default source for events that don't pass an explicit source. */
+    source?: Source;
+    /** Anonymous browser session identifier. NEVER a logged-in user identity. */
+    sessionId?: string;
+    /** React component-tree path from `<ErrorBoundary>`. No user input. */
+    componentStack?: string;
+    /** Payload-side ID for the org (Mongo ObjectID). Maps 1:1 with the SE
+     *  company below — they're two IDs for the same entity in different systems. */
+    organizationId?: string;
+    /** Display name, e.g. "Go Local Interactive". */
+    organizationName?: string;
+    /** SE-side numeric ID for the same org (e.g. 7). Used to pivot into SE admin. */
+    seCompanyId?: number;
+    /** SE renter UUID. SE calls this "tenant" — confusing in our multi-tenant
+     *  CMS context, hence the `se` prefix. */
+    seTenantId?: string;
+    /** Vendor-system renter ID (SiteLink/StorEdge/DoorSwap). */
+    vendorTenantId?: string;
+    /** Which underlying property-management system the org uses. */
+    vendorType?: "SiteLink" | "StorEdge" | "DoorSwap";
+    seFacilityId?: string | number;
+    vendorFacilityId?: string | number;
+    /** Vendor-side site/region code. */
+    siteLocationCode?: string;
+    seUnitId?: string | number;
+    vendorUnitId?: string | number;
+    /** Unit category slug (e.g. "5x10-storage"). */
+    unitCategorySlug?: string;
+    /** Pricing tier tag, e.g. "Tier 1" / "Tier 2". */
+    unitTier?: string;
+    /** Rate plan family, e.g. "standard_rate" | "tiered_rate" | "channel_rate" | "managed_rate". */
+    ratePlan?: string;
+    seReservationId?: string;
+    vendorReservationId?: string | number;
+    /** Hard hold (units locked) vs soft inquiry. */
+    reservationType?: "hard" | "soft";
+    /** SE-side UUID on the `vendor_rentals` table. */
+    seRentalId?: string;
+    /** Vendor-system rental ID (e.g. "R-1234567"). */
+    vendorRentalId?: string;
+    /** SE move-in event / transaction ID. */
+    seTransactionId?: string | number;
+    /** Vendor's ledger ID, surfaced via SE's `_se_ledger_id`. */
+    seLedgerId?: string | number;
+    /** Payment receipt ID (SE `_se_receipt_id`). */
+    seReceiptId?: string | number;
+    /** Single charge ID when one specific line item is the focus of the error. */
+    chargeId?: string;
+    /** Current invoice / one-time charges. Sub-keys are allowlisted by
+     *  `sanitizeIssueEventContext` — memo/note/comment fields are stripped. */
+    charges?: LogChargeLine[];
+    /** Recurring billing schedule. Same sub-key allowlist as `charges`. */
+    recurringFees?: LogChargeLine[];
+    promotionId?: string | number;
+    promotionSlug?: string;
+    insurancePlanId?: string | number;
+    paymentMethodType?: "cc" | "ach";
+    autopayEnabled?: boolean;
+    billingCycle?: "monthly" | "prepay";
+    /** ISO date the user picked. The date itself is not PII — it's a calendar
+     *  click, not who-they-are. */
+    moveInDate?: string;
+    /** Numeric rate the user *saw* on the page. Useful for "user saw $X but
+     *  was charged $Y" debugging without logging payment data. */
+    quotedRate?: number;
+    /** Which multi-step user flow the error occurred in. Pair with `step` —
+     *  `step` is meaningless without a flow reference (step 3 of *what*?).
+     *  Closed union so values stay grep-able across apps. */
+    flow?: "reservation" | "rental" | "cancellation" | "payment-update" | "onboarding";
+    /** Position within `flow` — number for ordered flows, slug for named ones.
+     *  Meaningful only when paired with `flow`. Different from `slug` (which
+     *  entity is in focus) and from the top-level `url` (where the user was). */
+    step?: number | string;
+    /** Stable identifier for the entity being acted on — page slug, market
+     *  slug, unit-category slug, etc. Decoupled from URL: a build-time SSG
+     *  error has no URL yet but the slug for the page being built does. */
+    slug?: string;
+    /** Which API/RPC was being called (e.g. "createReservationV2"). */
+    apiMethod?: string;
+    /** URL of the called endpoint, query string already stripped. */
+    apiEndpoint?: string;
+    httpStatus?: number;
+    /** Cache identifier when the error came from a stale-cache lookup. */
+    cacheKey?: string;
+    /** Mirrors `LogErrorOptions.reason` for filter convenience. */
+    errorTag?: string;
+    /** Closed schema field names, never user-typed values. e.g. `["cvv", "email"]`. */
+    validationFieldNames?: string[];
+    /** Soft-assertion expected count, e.g. "should have at least 1 unit, got 0". */
+    expectedCount?: number;
+    actualCount?: number;
+    collectionSlug?: string;
+    documentId?: string;
+    /** Which Payload hook fired the error (e.g. "beforeChange"). */
+    hookName?: string;
+    userRole?: "admin" | "super-admin" | "user" | "api-user";
+    /** AI-scraper batch ID. */
+    scraperBatchId?: string;
+    /** Build/deploy ID for build-trigger hooks. */
+    buildId?: string;
+}
+interface LogErrorOptions {
+    source?: Source;
+    severity?: Severity;
+    context?: LogContext;
+    /**
+     * Failure-classification code — the WHY behind the error. Closed enum
+     * (see `Reason`). Same code path failing for different reasons becomes
+     * distinct Issues, since `reason` is part of the fingerprint.
+     *
+     * If omitted, the event is uncaught/unclassified — fingerprint groups
+     * by `(source, message, top-stack-frame)` only.
+     */
+    reason?: Reason;
+}
+interface LogEvent {
+    source: Source;
+    repo: Repo;
+    severity: Severity;
+    fingerprint: string;
+    message: string;
+    stack: string;
+    context: LogContext;
+    url: string;
+    userAgent: string;
+    occurredAt: string;
+    release?: string;
+    /** Failure-classification code copied from `LogErrorOptions.reason`. */
+    reason?: Reason;
+}
+
+export type { InitLoggerConfig as I, LogContext as L, Reason as R, Severity as S, LogErrorOptions as a, LogChargeLine as b, LogEvent as c, Repo as d, Source as e };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@glidevvr/storage-payload-error-logger-pkg",
+  "version": "0.1.0",
+  "description": "Centralized error capture for GLI storage products (theme, unit-table, reservation, rental, login). Publishes a runtime helper for browsers and Node, a React error boundary, and a Payload v3 endpoint handler.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.mjs",
+      "require": "./dist/react/index.js"
+    },
+    "./payload-endpoint": {
+      "types": "./dist/payload-endpoint/index.d.ts",
+      "import": "./dist/payload-endpoint/index.mjs",
+      "require": "./dist/payload-endpoint/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "payload": "3.81.0",
+    "react": "18 || 19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "payload": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "16.3.2",
+    "@types/node": "20",
+    "@types/react": "19",
+    "@types/react-dom": "19",
+    "jsdom": "26.1.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "tsup": "8.5.1",
+    "typescript": "5",
+    "vitest": "2.1.9"
+  },
+  "type": "module",
+  "author": "Go Local Interactive",
+  "license": "ISC"
+}