@siteping/widget 0.9.9 → 0.9.11

package/dist/schema.d.ts

@@ -9,35 +9,70 @@
  * This is a TS representation, NOT a .prisma file.
  * The CLI generates the actual Prisma schema from this definition.
  */
-/** Definition of a single field in a Siteping database model. */
+/** Prisma scalar types supported by Siteping field definitions. */
+export type PrismaScalarType = "String" | "Boolean" | "Int" | "BigInt" | "Float" | "Decimal" | "DateTime" | "Json" | "Bytes";
+/** Prisma native column hints applied via `@db.<NativeType>`. */
+export type PrismaNativeType = "Text" | "VarChar" | "Char" | "MediumText" | "LongText" | (string & {});
+/** Relation cardinality between two Siteping models. */
+export type RelationKind = "1-to-many" | "many-to-1";
+/** Prisma `onDelete` referential action. */
+export type RelationOnDelete = "Cascade" | "Restrict" | "NoAction" | "SetNull" | "SetDefault";
+/**
+ * Relation metadata attached to a {@link FieldDef}.
+ *
+ * - `1-to-many` fields point at the related model and require no inverse
+ *   column on this side (`fields`/`references` are inferred by Prisma).
+ * - `many-to-1` fields own the foreign key — Prisma needs `fields` and
+ *   `references` to wire it up.
+ */
+export interface RelationDef {
+    kind: RelationKind;
+    model: string;
+    fields?: readonly string[];
+    references?: readonly string[];
+    onDelete?: RelationOnDelete;
+}
+/**
+ * Definition of a single field in a Siteping database model.
+ *
+ * The interface intentionally keeps a wide structural shape so it stays
+ * easy to extend, but consumers can narrow via {@link isRelationField} /
+ * {@link isScalarField} when relation vs. scalar logic diverges.
+ */
 export interface FieldDef {
-    type: string;
+    /** Prisma type (e.g. "String", "Int") for scalars, model name for relations. */
+    type: PrismaScalarType | (string & {});
+    /** Default literal (`"open"`) or function call (`now()`, `cuid()`). */
     default?: string;
+    /** Whether the column is nullable. */
     optional?: boolean;
-    relation?: {
-        kind: "1-to-many" | "many-to-1";
-        model: string;
-        fields?: string[];
-        references?: string[];
-        onDelete?: string;
-    };
+    /** Set on relation fields — absent on scalars. */
+    relation?: RelationDef;
     isId?: boolean;
     isUnique?: boolean;
     /** Prisma native type attribute (e.g. "Text" for @db.Text) — used for MySQL compatibility on long strings */
-    nativeType?: string;
+    nativeType?: PrismaNativeType;
     /** Prisma @updatedAt attribute */
     isUpdatedAt?: boolean;
 }
+/** Narrowing predicate: returns `true` when `field` declares a Prisma relation. */
+export declare function isRelationField(field: FieldDef): field is FieldDef & {
+    relation: RelationDef;
+};
+/** Narrowing predicate: returns `true` when `field` is a Prisma scalar (no relation metadata). */
+export declare function isScalarField(field: FieldDef): field is FieldDef & {
+    relation?: undefined;
+};
 /** Definition of a composite index on a Siteping database model. */
 export interface IndexDef {
-    fields: string[];
+    fields: readonly string[];
 }
 /** Definition of a single Siteping database model (fields + indexes). */
 export interface ModelDef {
     fields: Record<string, FieldDef>;
-    indexes?: IndexDef[];
+    indexes?: readonly IndexDef[];
 }
-export declare const SITEPING_MODELS: Readonly<{
+declare const _SITEPING_MODELS: {
     readonly SitepingFeedback: {
         readonly fields: {
             readonly id: {
@@ -111,12 +146,12 @@ export declare const SITEPING_MODELS: Readonly<{
                 };
             };
         };
-        readonly indexes: [{
-            readonly fields: ["projectName"];
+        readonly indexes: readonly [{
+            readonly fields: readonly ["projectName"];
         }, {
-            readonly fields: ["projectName", "status", "createdAt"];
+            readonly fields: readonly ["projectName", "status", "createdAt"];
         }, {
-            readonly fields: ["projectName", "url"];
+            readonly fields: readonly ["projectName", "url"];
         }];
     };
     readonly SitepingAnnotation: {
@@ -134,8 +169,8 @@ export declare const SITEPING_MODELS: Readonly<{
                 readonly relation: {
                     readonly kind: "many-to-1";
                     readonly model: "SitepingFeedback";
-                    readonly fields: ["feedbackId"];
-                    readonly references: ["id"];
+                    readonly fields: readonly ["feedbackId"];
+                    readonly references: readonly ["id"];
                     readonly onDelete: "Cascade";
                 };
             };
@@ -210,8 +245,15 @@ export declare const SITEPING_MODELS: Readonly<{
                 readonly default: "now()";
             };
         };
-        readonly indexes: [{
-            readonly fields: ["feedbackId"];
+        readonly indexes: readonly [{
+            readonly fields: readonly ["feedbackId"];
         }];
     };
-}>;
+};
+/** Map of Siteping models keyed by model name — frozen at runtime. */
+export declare const SITEPING_MODELS: typeof _SITEPING_MODELS;
+/** Union of every Siteping model name as a string literal. */
+export type SitepingModelName = keyof typeof SITEPING_MODELS;
+/** Field names declared on a specific Siteping model. */
+export type SitepingModelFieldName<M extends SitepingModelName> = keyof (typeof SITEPING_MODELS)[M]["fields"];
+export {};

package/dist/siteping-core.d.ts

@@ -1,8 +1,11 @@
+export type { SitepingErrorCode } from "./errors.js";
 export { SitepingAuthError, SitepingError, SitepingNetworkError, SitepingValidationError } from "./errors.js";
 export type { FilterResult } from "./filters.js";
 export { applyFeedbackFilters } from "./filters.js";
-export type { FieldDef, IndexDef, ModelDef } from "./schema.js";
-export { SITEPING_MODELS } from "./schema.js";
+export type { FieldDef, IndexDef, ModelDef, PrismaNativeType, PrismaScalarType, RelationDef, RelationKind, RelationOnDelete, SitepingModelFieldName, SitepingModelName, } from "./schema.js";
+export { isRelationField, isScalarField, SITEPING_MODELS } from "./schema.js";
 export type { ScreenshotStorage } from "./screenshot-storage.js";
-export type { AnchorData, AnnotationCreateInput, AnnotationPayload, AnnotationRecord, AnnotationResponse, ConsoleDiagnosticEntry, DiagnosticsSnapshot, FeedbackCreateInput, FeedbackPayload, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackStatus, FeedbackType, FeedbackUpdateInput, NetworkDiagnosticEntry, PageScope, RectData, SitepingConfig, SitepingInstance, SitepingPublicEvents, SitepingStore, } from "./types.js";
-export { FEEDBACK_STATUSES, FEEDBACK_TYPES, flattenAnnotation, isStoreDuplicate, isStoreNotFound, StoreDuplicateError, StoreNotFoundError, } from "./types.js";
+export type { AssertEqual, Brand, DeepReadonly, IfEquals, KeysOfType, NonEmptyArray, Prettify, Replace, RequiredNonNull, } from "./type-utils.js";
+export { hasOwn, isRecord } from "./type-utils.js";
+export type { AnchorData, AnnotationCreateInput, AnnotationPayload, AnnotationRecord, AnnotationResponse, BuiltinLocale, ConsoleDiagnosticEntry, ConsoleDiagnosticLevel, DiagnosticsCaptureOptions, DiagnosticsSnapshot, FeedbackCreateInput, FeedbackPage, FeedbackPayload, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackResponseList, FeedbackStatus, FeedbackType, FeedbackUpdateInput, NetworkDiagnosticEntry, PageScope, RectData, SitepingConfig, SitepingDeepLinkOptions, SitepingIdentity, SitepingInstance, SitepingLocale, SitepingPosition, SitepingPublicEventListener, SitepingPublicEvents, SitepingSkipReason, SitepingStore, SitepingTheme, SitepingUnsubscribe, } from "./types.js";
+export { BUILTIN_LOCALES, FEEDBACK_STATUSES, FEEDBACK_TYPES, flattenAnnotation, isStoreDuplicate, isStoreNotFound, StoreDuplicateError, StoreNotFoundError, } from "./types.js";

package/dist/types.d.ts

@@ -1,3 +1,36 @@
+import { type Prettify } from "./type-utils.js";
+/** FAB anchor — bottom-corner placement supported by the widget. */
+export type SitepingPosition = "bottom-right" | "bottom-left";
+/** Visual theme — `auto` resolves to `light` or `dark` via system preference. */
+export type SitepingTheme = "light" | "dark" | "auto";
+/** Built-in UI locales shipped with the widget. */
+export declare const BUILTIN_LOCALES: readonly ["en", "fr", "de", "es", "it", "pt", "ru"];
+export type BuiltinLocale = (typeof BUILTIN_LOCALES)[number];
+/**
+ * Locale identifier accepted by the widget. Built-in locales are kept as
+ * literal strings so editors auto-complete them, but arbitrary BCP-47 tags
+ * are also accepted (custom dictionaries registered via `registerLocale`).
+ */
+export type SitepingLocale = BuiltinLocale | (string & {});
+/** Reasons reported through `SitepingConfig.onSkip`. */
+export type SitepingSkipReason = "production" | "mobile";
+/** Per-channel + per-buffer-size diagnostics configuration. */
+export interface DiagnosticsCaptureOptions {
+    console?: boolean;
+    network?: boolean;
+    maxConsoleEntries?: number;
+    maxNetworkEntries?: number;
+}
+/** Identity payload supplied by the host application — bypasses the modal. */
+export interface SitepingIdentity {
+    name: string;
+    email: string;
+}
+/** Deep-link configuration — controls how a feedback id is read from the URL. */
+export interface SitepingDeepLinkOptions {
+    /** Query parameter name carrying the feedback id. Defaults to `"siteping"`. */
+    param?: string;
+}
 /** Configuration options for the Siteping widget. */
 export interface SitepingConfig {
     /** HTTP endpoint that receives feedbacks (e.g. '/api/siteping'). Required unless `store` is provided. */
@@ -7,7 +40,7 @@ export interface SitepingConfig {
     /** Direct store for client-side mode. When set, bypasses HTTP and uses the store directly in the browser. */
     store?: SitepingStore | undefined;
     /** FAB position — defaults to 'bottom-right' */
-    position?: "bottom-right" | "bottom-left";
+    position?: SitepingPosition;
     /** Accent color for the widget UI — defaults to '#0066ff' */
     accentColor?: string;
     /** Show the widget even in production — defaults to false */
@@ -15,9 +48,9 @@ export interface SitepingConfig {
     /** Enable debug logging of lifecycle events — defaults to false */
     debug?: boolean;
     /** Color theme — defaults to 'light' */
-    theme?: "light" | "dark" | "auto";
+    theme?: SitepingTheme;
     /** UI locale — defaults to 'en'. Built-in: en, fr, de, es, it, pt (Brazilian), ru. Any other string falls back to English. */
-    locale?: "en" | "fr" | "de" | "es" | "it" | "pt" | "ru" | (string & {}) | undefined;
+    locale?: SitepingLocale | undefined;
     /**
      * Returns the current page scope for annotations and panel filtering.
      * Called on initial markers load and on `instance.refresh()`.
@@ -74,14 +107,33 @@ export interface SitepingConfig {
      * URL (with query string) but never the response body. Inform end users
      * before enabling in environments where they might log sensitive values.
      */
-    captureDiagnostics?: boolean | {
-        console?: boolean;
-        network?: boolean;
-        maxConsoleEntries?: number;
-        maxNetworkEntries?: number;
-    } | undefined;
+    captureDiagnostics?: boolean | DiagnosticsCaptureOptions | undefined;
     /** Called when the widget is skipped (production mode, mobile viewport) */
-    onSkip?: (reason: "production" | "mobile") => void;
+    onSkip?: (reason: SitepingSkipReason) => void;
+    /**
+     * Auto-focus a specific annotation when its ID appears in the URL query
+     * string. Lets hosts deeplink directly into a feedback from external
+     * systems (Zammad tickets, Slack notifications, dashboard rows).
+     *
+     * When enabled, the widget reads the configured query parameter from
+     * `window.location.search` right after the initial markers load. If the
+     * value matches a visible feedback ID, the widget scrolls the annotation
+     * into view, pins its highlight, and pulses the marker — the same visual
+     * affordance a marker click produces.
+     *
+     * - `false` / `undefined` (default): no URL parsing. Existing behavior
+     *   unchanged, no host URL inspection.
+     * - `true`: enabled with default query parameter name `siteping`.
+     * - object: enabled with a custom parameter name. Use this to avoid
+     *   clashes with host-app query keys.
+     *
+     * Only the initial load triggers focus. Subsequent URL changes (SPA
+     * navigation, `history.pushState`, hash updates) are ignored —
+     * deliberate, to avoid surprising re-scrolls during normal browsing.
+     * Hosts that need re-focus on route change can call
+     * `instance.focusFeedback(id)` explicitly.
+     */
+    deepLink?: boolean | SitepingDeepLinkOptions | undefined;
     /**
      * Pre-fill author identity from the host application — typically the
      * currently signed-in user. When set, the widget uses these values
@@ -101,10 +153,7 @@ export interface SitepingConfig {
      * https://github.com/NeosiaNexus/SitePing/issues/85 for tracking a
      * future enhancement that propagates identity updates without a remount.
      */
-    identity?: {
-        name: string;
-        email: string;
-    } | undefined;
+    identity?: SitepingIdentity | undefined;
     /** Called when the feedback panel is opened. */
     onOpen?: () => void;
     /** Called when the feedback panel is closed. */
@@ -137,15 +186,30 @@ export interface SitepingInstance {
     close: () => void;
     /** Reload feedbacks from server */
     refresh: () => void;
+    /**
+     * Scroll the matching annotation into view, pin its highlight, and
+     * pulse its marker. Returns `true` when a visible feedback matched the
+     * given ID, `false` otherwise (unknown ID, feedback on another URL when
+     * `scopeAnnotationsByUrl` filtered it out, or markers not yet loaded).
+     *
+     * Counterpart to the `deepLink` config option for hosts that prefer to
+     * drive focus from JS (e.g., a notification click handler) instead of a
+     * URL query parameter.
+     */
+    focusFeedback: (feedbackId: string) => boolean;
     /** Subscribe to a public widget event */
-    on: <K extends keyof SitepingPublicEvents>(event: K, listener: (...args: SitepingPublicEvents[K]) => void) => () => void;
+    on: <K extends keyof SitepingPublicEvents>(event: K, listener: SitepingPublicEventListener<K>) => SitepingUnsubscribe;
     /** Unsubscribe from a public widget event */
-    off: <K extends keyof SitepingPublicEvents>(event: K, listener: (...args: SitepingPublicEvents[K]) => void) => void;
+    off: <K extends keyof SitepingPublicEvents>(event: K, listener: SitepingPublicEventListener<K>) => void;
 }
+/** Listener signature for a single `SitepingPublicEvents` key. */
+export type SitepingPublicEventListener<K extends keyof SitepingPublicEvents> = (...args: SitepingPublicEvents[K]) => void;
+/** Disposer returned by `SitepingInstance.on` — call once to detach the listener. */
+export type SitepingUnsubscribe = () => void;
 /** Events exposed to consumers via SitepingInstance.on / .off */
 export interface SitepingPublicEvents {
     "feedback:sent": [FeedbackResponse];
-    "feedback:deleted": [string];
+    "feedback:deleted": [FeedbackResponse["id"]];
     "panel:open": [];
     "panel:close": [];
 }
@@ -340,12 +404,21 @@ export declare class StoreDuplicateError extends Error {
     readonly code: "STORE_DUPLICATE";
     constructor(message?: string);
 }
+/** Shape of any ORM error that carries a Prisma-style `code` field. */
+type CodedError<C extends string = string> = {
+    code: C;
+};
 /** Type guard — works for `StoreNotFoundError` and ORM-specific equivalents (e.g. Prisma P2025). */
-export declare function isStoreNotFound(error: unknown): boolean;
+export declare function isStoreNotFound(error: unknown): error is StoreNotFoundError | CodedError<"P2025">;
 /** Type guard — works for `StoreDuplicateError` and ORM-specific equivalents (e.g. Prisma P2002). */
-export declare function isStoreDuplicate(error: unknown): boolean;
+export declare function isStoreDuplicate(error: unknown): error is StoreDuplicateError | CodedError<"P2002">;
 /** Flatten a widget `AnnotationPayload` (nested anchor + rect) into a flat `AnnotationCreateInput`. */
-export declare function flattenAnnotation(ann: AnnotationPayload): AnnotationCreateInput;
+export declare function flattenAnnotation(ann: AnnotationPayload): Prettify<AnnotationCreateInput>;
+/** Paginated result returned by `SitepingStore.getFeedbacks`. */
+export interface FeedbackPage {
+    feedbacks: FeedbackRecord[];
+    total: number;
+}
 /**
  * Abstract storage interface for Siteping.
  *
@@ -366,10 +439,7 @@ export interface SitepingStore {
     /** Create a feedback with its annotations. Idempotent on `clientId` — return existing record on duplicate, or throw `StoreDuplicateError`. */
     createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord>;
     /** Paginated query with optional filters. Returns empty array (not error) when no results. */
-    getFeedbacks(query: FeedbackQuery): Promise<{
-        feedbacks: FeedbackRecord[];
-        total: number;
-    }>;
+    getFeedbacks(query: FeedbackQuery): Promise<FeedbackPage>;
     /** Lookup by client-generated UUID. Returns `null` (not error) when not found. */
     findByClientId(clientId: string): Promise<FeedbackRecord | null>;
     /** Update status/resolvedAt. Throws `StoreNotFoundError` if `id` does not exist. */
@@ -409,9 +479,11 @@ export interface FeedbackPayload {
      */
     diagnostics?: DiagnosticsSnapshot | null | undefined;
 }
+/** Severity levels persisted in `ConsoleDiagnosticEntry`. */
+export type ConsoleDiagnosticLevel = "log" | "info" | "warn" | "error";
 /** A single console entry captured by `ConsoleBuffer`. */
 export interface ConsoleDiagnosticEntry {
-    level: "log" | "info" | "warn" | "error";
+    level: ConsoleDiagnosticLevel;
     /** ISO 8601 timestamp captured at log time. */
     timestamp: string;
     /** Best-effort string representation of the original console args. */
@@ -537,3 +609,9 @@ export interface AnnotationResponse {
     devicePixelRatio: number;
     createdAt: string;
 }
+/** Paginated `FeedbackResponse` shape returned by the API. */
+export interface FeedbackResponseList {
+    feedbacks: FeedbackResponse[];
+    total: number;
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siteping/widget",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "description": "Feedback widget for client review during development — annotations, bugs, questions directly on the site",
   "type": "module",
   "sideEffects": false,