@ngis/plugin-sdk 0.4.0

package/dist/src/types/gis.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Shared UI types for the GIS workspace (`type=GIS` scratch scene).
+ * Kept separate from `analysis.ts` / `map-styling.ts` so the GIS surface can
+ * evolve without coupling to the other workspaces.
+ */
+/** Left dock tab: the layer stack vs. the scene's data (resources). */
+export type GisLeftTab = "layers" | "data";
+/**
+ * Lifecycle state of the scratch workspace:
+ * - `opening`  — calling `GET /gis/workspace`
+ * - `prompt`   — prior session has content; awaiting Restore vs. Start empty
+ * - `ready`    — workspace scene loaded and rendered
+ * - `error`    — open/load failed
+ */
+export type GisWorkspaceStatus = "opening" | "prompt" | "ready" | "error";
+/** Camera state persisted to / restored from `scene.configJson`. */
+export interface GisViewport {
+    center: [number, number];
+    zoom: number;
+    pitch?: number;
+    bearing?: number;
+}
+/**
+ * Protomaps hosted-style theme that backs the basemap switcher. Mapped straight
+ * to the `SceneMapCanvas` `basemap` prop (the Protomaps v5 theme segment).
+ */
+export type GisBasemap = "light" | "dark" | "white" | "grayscale" | "black";
+/** Basemap options shown in the switcher, in display order. */
+export declare const GIS_BASEMAPS: readonly GisBasemap[];
+export declare const GIS_DEFAULT_BASEMAP: GisBasemap;
+/**
+ * Terra Draw modes the rail drives directly (a subset of the library's modes).
+ * Each maps 1:1 to `TerraDraw.setMode(mode)`.
+ */
+export type GisDrawMode = "point" | "linestring" | "polygon" | "rectangle" | "circle" | "text" | "select";
+/**
+ * The measurement flavours the rail can start. Distinct from `GisDrawMode`:
+ * measuring is an ephemeral overlay (its own isolated Terra Draw instance via
+ * `MaplibreMeasureControl`), never a drawn feature.
+ */
+export type GisMeasureKind = "distance" | "area";
+/**
+ * What the cursor snaps to while drawing lines/polygons or measuring:
+ * `node` = existing vertices only, `edge` = nearest point on a segment only,
+ * `both` = vertices win over edges when both are in range.
+ */
+export type GisSnapTarget = "node" | "edge" | "both";
+/**
+ * Shared snapping configuration applied to BOTH the draw and measure Terra Draw
+ * controls (via their `modeOptions` → `snapping.toCustom`). One config drives
+ * both tool sets, matching the reason measuring was migrated onto the library
+ * control. Note: Terra Draw only supports snapping on line/polygon modes, so
+ * rectangle/circle/point/text draw tools are unaffected.
+ */
+export interface GisSnapConfig {
+    /** Master on/off. When false, `toCustom` returns undefined (no snap). */
+    enabled: boolean;
+    /** Snap to vertices, edges, or both (node-priority). */
+    target: GisSnapTarget;
+    /** Snap radius in screen pixels. */
+    tolerancePx: number;
+    /**
+     * Scene-layer ids to snap to. `null` means "all currently visible scene
+     * layers"; a list narrows snapping to just those layers. Runtime-only (layer
+     * ids are scene-specific, so this is never persisted).
+     */
+    layerIds: string[] | null;
+    /**
+     * Also snap across controls — drawing snaps to measured geometry and vice
+     * versa (each control reads the other's Terra Draw snapshot).
+     */
+    includeDrawnFeatures: boolean;
+}
+/** Sensible starting snapping config: off, both targets, 10px, all layers. */
+export declare const GIS_DEFAULT_SNAP_CONFIG: GisSnapConfig;
+/**
+ * Stable ids for every catalog entry. Persisted inside the saved layout — treat
+ * this as an append-only enum (never renumber or repurpose an existing id).
+ */
+export type GisToolId = "draw-point" | "draw-line" | "draw-polygon" | "draw-rectangle" | "draw-circle" | "draw-text" | "select" | "delete-selection" | "delete-all" | "undo" | "redo" | "export" | "attribute-table" | "basemap" | "zoom-in" | "zoom-out" | "home" | "measure-distance" | "measure-area" | "snapping" | "code" | "workflow" | "tools" | "style" | "ai" | "plugins" | "measure" | "identify" | "select-by-attribute";
+/**
+ * Items persisted in the customizable rail. `GisToolId` remains the frozen
+ * command catalog; host-only composite controls can ride on the rail without
+ * becoming invocable map tools.
+ */
+export type GisRailItemId = GisToolId | "multi-view" | "flow-field";
+/** How a tool behaves when invoked from the rail. */
+export type GisToolKind = "mode" | "measure" | "action" | "dropdown";
+/** One-shot actions the rail fires on the map via the imperative handle
+ * (plus `code-panel`, which toggles the code dock instead of the map). */
+export type GisToolAction = "delete-selection" | "delete-all" | "undo" | "redo" | "export" | "attribute-table" | "code-panel" | "workflow-panel" | "tools-panel" | "style-panel" | "ai-panel" | "zoom-in" | "zoom-out" | "home";
+/** Catalog grouping used by the customize dialog. */
+export type GisToolCategory = "draw" | "measure" | "edit" | "history" | "data" | "navigation" | "analysis";
+/** Minimal slice of `WorkspacePanelRegistry` a rail tool's `invoke` needs. */
+export interface GisRailPanelControl {
+    open: (slot: "right" | "bottom", id: string) => void;
+    toggle: (slot: "right" | "bottom", id: string) => void;
+    setActive: (slot: "right" | "bottom", id: string | null) => void;
+    getActive: (slot: "right" | "bottom") => string | null;
+}
+/**
+ * Minimal slice of the `NgisMapAPI` facade (`sdk/map-api.ts`) a rail tool's
+ * `invoke` needs — draw / measure / camera commands plus the panel registry.
+ * The concrete facade has a far larger surface; this is just what the rail
+ * exercises, so the real `NgisMapAPI` satisfies it structurally.
+ */
+export interface GisRailApi {
+    draw: {
+        setMode: (mode: GisDrawMode) => void;
+        cancelMode: () => void;
+        clear: () => void;
+        deleteSelection: () => void;
+        undo: () => void;
+        redo: () => void;
+        export: () => void;
+        getActiveMode: () => string | null;
+    };
+    measure: {
+        start: (kind: GisMeasureKind) => void;
+        clear: () => void;
+    };
+    camera: {
+        zoomIn: () => void;
+        zoomOut: () => void;
+        zoomHome: () => void;
+        /** Structural mirror of `NgisCameraFacet.getView` (additive widening,
+         * session P5 — the dynamic rail-tool path reads the current center).
+         * `null` until the facade's raw map is bound. */
+        getView: () => {
+            center: [number, number];
+            zoom: number;
+            pitch?: number;
+            bearing?: number;
+        } | null;
+    };
+    panels: GisRailPanelControl;
+}
+/** Minimal slice of `useGisRailStore` a rail tool's `invoke` needs. */
+export interface GisRailStoreHandle {
+    getState: () => {
+        activeToolId: GisToolId | null;
+        actions: {
+            setActiveMode: (mode: GisDrawMode | null, toolId: GisToolId | null) => void;
+            setActiveMeasure: (kind: GisMeasureKind | null, toolId: GisToolId | null) => void;
+            clearActive: () => void;
+        };
+    };
+}
+/**
+ * ctx passed to `GisToolDef.invoke`. v1 (C8) exposes the `NgisMapAPI` facade
+ * (replacing C7's raw `{ mapHandle }` ref — the facade subsumes it and adds the
+ * panel registry the old `onToggleAttributeTable`/`onToggleWorkflow` callbacks
+ * used to cover) and the rail store (for the active-tool lit-state bookkeeping
+ * a toggle needs). Both fields are structural, so future widening stays additive.
+ */
+export interface GisRailInvokeContext {
+    api: GisRailApi;
+    railStore: GisRailStoreHandle;
+}
+/** A single catalog entry. `icon` is a lucide name resolved in-component. */
+export interface GisToolDef {
+    id: GisToolId;
+    icon: string;
+    /** i18n key suffix under `GIS.rail.tools.*`. */
+    labelKey: string;
+    category: GisToolCategory;
+    kind: GisToolKind;
+    /** For `kind: "mode"` — the Terra Draw mode to activate. */
+    drawMode?: GisDrawMode;
+    /** For `kind: "measure"` — the measurement flavour to start. */
+    measureKind?: GisMeasureKind;
+    /** For `kind: "action"` — the imperative handle method to call. */
+    action?: GisToolAction;
+    /** Whether the tool unfolds the contextual readout strip while active. */
+    hasContextStrip?: boolean;
+    /** Disabled "coming soon" catalog entry — rendered greyed, not invocable. */
+    disabled?: boolean;
+    /**
+     * Hide this tool whenever its backing panel is not registered. The tool id
+     * remains in persisted layouts so disabling a plugin is reversible: when
+     * the panel registers again, its button returns to the user's saved place.
+     */
+    requiredPanel?: {
+        slot: "right" | "bottom";
+        id: string;
+    };
+    /** Invoked by `GisCommandRail`'s dispatcher in place of the old hardcoded
+     * switch. Absent for `kind: "dropdown"` entries (`basemap`/`snapping`),
+     * which render their own inline UI and never go through the dispatcher. */
+    invoke?: (ctx: GisRailInvokeContext) => void;
+}
+export interface GisHostRailItemDef {
+    id: Exclude<GisRailItemId, GisToolId>;
+    icon: string;
+    /** i18n key suffix under `GIS.rail.tools.*`. */
+    labelKey: string;
+    category: GisToolCategory;
+    kind: "host";
+}
+export type GisRailItemDef = GisToolDef | GisHostRailItemDef;
+/** One user-named cluster of tools on the rail. */
+export interface GisRailGroup {
+    id: string;
+    /** Custom name; when null, render the default i18n label for `nameKey`. */
+    name: string | null;
+    /** Default-group i18n key under `GIS.rail.groups.*` (seeded groups only). */
+    nameKey?: string;
+    /** Ordered, visible tools in this group. */
+    toolIds: GisRailItemId[];
+}
+/**
+ * Per-user persisted rail layout. A tool is "pinned to the bar" exactly when it
+ * lives in a group; every other catalog tool stays reachable from the "More
+ * tools" overflow menu. Deleting a group simply returns its tools to overflow —
+ * nothing is ever lost.
+ */
+export interface GisRailLayout {
+    version: number;
+    groups: GisRailGroup[];
+}
+/** Live measurement readout shown in the rail's contextual strip. */
+export interface GisMeasureSummary {
+    /** Vertex count of the measured path / polygon ring. */
+    points: number;
+    /** Total path length (distance) or polygon perimeter (area), in meters. */
+    lengthMeters: number;
+    /** Polygon area in square meters (0 for a distance measurement). */
+    areaSqMeters: number;
+}
+/** Live geometry readout shown in the rail's contextual strip. */
+export interface GisDrawSummary {
+    /** Number of user-drawn features currently on the map. */
+    features: number;
+    /** Total vertex count across those features. */
+    vertices: number;
+    /** Total line length in meters (linestrings). */
+    lengthMeters: number;
+    /** Total polygon area in square meters. */
+    areaSqMeters: number;
+    /** Scene features intersected by the drawn geometry (draw-to-query). */
+    matched: number;
+}

package/dist/src/types/market-social.d.ts

@@ -0,0 +1,378 @@
+/**
+ * DTOs for the Stage 15 **community market** — ratings, comments, abuse reports,
+ * install counts, the recipe flywheel counter, extension packs, and the
+ * verified-publisher flag.
+ *
+ * **Authored at the W1 kickoff and read-only to the wave** (the YD48 rule: a
+ * signature is not a seam — shared shapes are implemented once, by the kickoff,
+ * and no session re-declares one). ZB1 owns the ratings/comments/reports/
+ * install-count/stats wire; ZB2 owns packs; ZB3 owns the verified-publisher
+ * flag. Z4/Z5/Z6 consume these types and the byte-identical fixtures beside
+ * them (`src/types/__fixtures__/market-social/`) — never invented shapes.
+ *
+ * Field names are the **wire** names; nothing is renamed to taste. Java
+ * `Instant` serializes as an ISO-8601 `string`. The paging envelope is the one
+ * that already exists — {@link PageResult} — never a second one.
+ *
+ * Contract: `docs/open_ecosystem_stage/README.md` → **F15.5** (ratings/comments/
+ * reports), **F15.6** (install counts + flywheel), **F15.7** (packs), **F15.11**
+ * (verified publisher), **F15.18** (this module and its fixture set).
+ *
+ * Every surface here is **G-B**: authenticated, LAN-only, no anonymous row. Every
+ * record carries the authenticated user id.
+ */
+import type { PageResult } from "./common";
+/**
+ * Integer 1–5. Modelled as a union rather than `number` so a client cannot post
+ * a 0 or a 6 past the type checker — the server rejects them either way, but the
+ * refusal should not need a round trip to discover.
+ */
+export type RatingValue = 1 | 2 | 3 | 4 | 5;
+/** Server-side cap on {@link RatingDto.text}, measured on the serialized UTF-8. */
+export declare const RATING_TEXT_MAX_LENGTH = 2000;
+/**
+ * One user's rating of one extension.
+ *
+ * **Installers only at creation** — the server requires an install row for
+ * (user, extension) at write time. It is *not* required afterward: a rating
+ * **survives uninstall**, because the recorded experience was real (F15.5).
+ * One per (user, extension), a UNIQUE constraint rather than a convention, and
+ * **editable in place** — an opinion is not an immutable artifact, so there is
+ * no version here.
+ */
+export interface RatingDto {
+    extId: string;
+    /** The rating's author. Always present — there is no anonymous surface. */
+    userId: string;
+    value: RatingValue;
+    /** `null` when the rater left a score and no words. */
+    text: string | null;
+    createdAt: string;
+    /** Equal to {@link createdAt} until the first in-place edit. */
+    updatedAt: string;
+}
+/** `POST`/`PUT /api/extensions/{extId}/rating` — the caller is the authenticated user. */
+export interface RatingUpsertRequest {
+    value: RatingValue;
+    /** Omit or `null` to score without text; over {@link RATING_TEXT_MAX_LENGTH} is a `400`. */
+    text?: string | null;
+}
+/**
+ * Aggregate shown on the market card and detail page.
+ *
+ * **Shown from the first rating** — no display threshold. A LAN community is too
+ * small for one to buy anything, and every surface is authenticated anyway
+ * (F15.5). `mean` is rounded to one decimal server-side; `count` 0 means nothing
+ * has been rated and `mean` is `null`, never `0` (a 0 would render as a real
+ * score).
+ */
+export interface RatingAggregateDto {
+    extId: string;
+    count: number;
+    mean: number | null;
+}
+/**
+ * **Flat v1 — no threads.** There is deliberately no `parentId`: adding one
+ * later is additive, while shipping a tree that nothing renders is not.
+ *
+ * Author may edit and delete their own; **ADMIN may hard-delete any**, which
+ * writes an audit event recording actor and target. Moderation is
+ * report-driven, not pre-moderated — a comment posts immediately under G-B.
+ */
+export interface CommentDto {
+    id: string;
+    extId: string;
+    authorId: string;
+    body: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `POST /api/extensions/{extId}/comments` and the author's in-place edit. */
+export interface CommentUpsertRequest {
+    body: string;
+}
+/** What a report points at. An extension, or one social row on it. */
+export type ReportTargetType = "EXTENSION" | "COMMENT" | "RATING";
+/**
+ * `OPEN → RESOLVED | DISMISSED`. Transitions are **ADMIN-only**, and the two
+ * terminal states are terminal: a fresh concern about the same target is a new
+ * report, never a reopen.
+ */
+export type ReportStatus = "OPEN" | "RESOLVED" | "DISMISSED";
+/**
+ * One abuse report.
+ *
+ * **One OPEN report per (reporter, target)** — a duplicate submission returns
+ * the existing row rather than minting queue noise, so a client may treat
+ * submit as idempotent while the first report is still open.
+ */
+export interface ReportDto {
+    id: string;
+    targetType: ReportTargetType;
+    targetId: string;
+    /** The extension the target belongs to — present even when the target is a comment
+     *  or rating, so the ADMIN queue can group without a second lookup. */
+    extId: string;
+    reporterId: string;
+    /** Required and non-blank at submission. */
+    reason: string;
+    status: ReportStatus;
+    /** ADMIN's optional note, written at the transition. `null` while `OPEN`. */
+    resolutionNote: string | null;
+    /** The ADMIN who moved it out of `OPEN`. `null` while `OPEN`. */
+    resolvedBy: string | null;
+    resolvedAt: string | null;
+    createdAt: string;
+}
+/** `POST /api/extensions/{extId}/reports`. */
+export interface ReportCreateRequest {
+    targetType: ReportTargetType;
+    targetId: string;
+    reason: string;
+}
+/** `POST /api/extensions/reports/{id}/resolve` \| `/dismiss` — ADMIN only. */
+export interface ReportTransitionRequest {
+    resolutionNote?: string | null;
+}
+/**
+ * The ADMIN report queue — **paged from day one**, the lesson of the review
+ * queue that shipped as a plain unpaged array (Track B substrate, item 4).
+ */
+export type ReportQueuePage = PageResult<ReportDto>;
+/**
+ * `GET /api/extensions/stats/recipes` — **the exit criterion's "community-recipe
+ * counting exists"**, open to any authenticated caller (it exposes no ownership
+ * detail, only cohort totals).
+ *
+ * Counts **PUBLISHED recipe-bearing versions**: a `tool`-kind reference version
+ * whose referenced tool has `provider = "workflow"`. Both granularities ship
+ * because they answer different questions — `*Versions` measures activity,
+ * `*Extensions` measures breadth.
+ *
+ * **Cohort is the owner's role at query time**, which is documented rather than
+ * denormalized: an owner promoted to ADMIN reclassifies their history. Accepted
+ * at LAN scale. The flywheel *signal* (community > 1× first-party) is measured
+ * at +6 months; this stage owes only the counting.
+ */
+export interface RecipeStatsDto {
+    adminVersions: number;
+    communityVersions: number;
+    adminExtensions: number;
+    communityExtensions: number;
+    /** When the counts were taken, ISO-8601. */
+    asOf: string;
+}
+/**
+ * The additive fields Stage 15 lands on the **existing** `ExtensionSummaryDto` /
+ * `ExtensionDetailDto`. Declared as a separate interface here so ZB1's additive
+ * change and Z4's consumption agree before either is written; the shipped
+ * `ExtensionSummary` in `./extensions` gains these members, it is not replaced.
+ *
+ * `installCount` is `COUNT(ngis_extension_install WHERE enabled = true)` — a
+ * disabled install is not adoption, and uninstall already deletes the row.
+ * Shown from **1**, no threshold.
+ */
+export interface ExtensionSocialFields {
+    installCount: number;
+    /** `null` until the first rating — never a synthetic 0-star aggregate. */
+    rating: RatingAggregateDto | null;
+    /** F15.11 — an operator attestation about the *publisher*, carried on the extension
+     *  because that is where the market renders it. Confers zero capability. */
+    publisherVerified: boolean;
+}
+/**
+ * What the badge attests on a LAN deployment: **the operator knows who this
+ * publisher is.** Identity attestation by the deployment's operator, nothing
+ * more — not code review, not an endorsement, and it grants no extra capability.
+ *
+ * ADMIN-granted and revocable; there is **no self-serve path this stage**
+ * (DNS-TXT-style self-verification is a G-C-era design, deliberately out).
+ * Stored in `ngis-extension` riding migration **V5** — never in `ngis-auth`: no
+ * cross-service migration is declared for this stage, and this is a market
+ * concept, not an account one.
+ */
+export interface VerifiedPublisherDto {
+    userId: string;
+    verified: boolean;
+    /** The ADMIN who last granted or revoked. */
+    grantedBy: string;
+    grantedAt: string;
+    /** Free-text operator note recording *how* identity was established. */
+    note: string | null;
+}
+/** `PUT /api/extensions/publishers/{userId}/verified` — ADMIN only. */
+export interface VerifiedPublisherRequest {
+    verified: boolean;
+    note?: string | null;
+}
+/**
+ * Packs are **new tables** (migration V6), never a fourth `ExtensionKind`.
+ * A kind would ripple through every wire enum, the frozen
+ * `PackageManifestValidator`, the G-D `kind === "ui-plugin"` filters and every
+ * client narrowing on the three-kind union — for a thing that is a *grouping*,
+ * not an artifact.
+ *
+ * The ACL vocabulary is the extension one **minus `GROUP`** (F15.16: no
+ * group-membership service exists platform-wide to resolve against).
+ */
+export type PackVisibility = "PRIVATE" | "PUBLIC";
+/** One curated member. Order is the pack author's; it is presentation, not dependency. */
+export interface PackMemberDto {
+    extId: string;
+    /** 0-based position in the curated list. */
+    position: number;
+    /** Denormalized for rendering the pack without N detail fetches. */
+    displayName: string;
+    kind: string;
+}
+/**
+ * A pack **curates identity, not versions**: it pins no member version. Each
+ * member installs under the user's normal version policy (`LATEST` by default,
+ * pin-able per install afterward) exactly as a direct install would — versions
+ * stay the registry's business.
+ */
+export interface PackDto {
+    packId: string;
+    ownerId: string;
+    displayName: string;
+    summary: string | null;
+    visibility: PackVisibility;
+    members: PackMemberDto[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** Per-member result of a pack install. */
+export type PackInstallStatus = "INSTALLED" | "ALREADY_INSTALLED" | "FAILED";
+/**
+ * One member's outcome.
+ *
+ * **A member the caller cannot see FAILs with a reason — a pack is never an ACL
+ * bypass.** That is the standing install-is-adoption-never-bypass rule extended
+ * to packs, and it is why this is a per-member report rather than a single
+ * status code.
+ */
+export interface PackInstallMemberResultDto {
+    extId: string;
+    status: PackInstallStatus;
+    /** Present iff `status === "FAILED"`. */
+    reason: string | null;
+}
+/**
+ * **No rollback.** Members that installed stay installed when a sibling fails;
+ * existing installs are left untouched (`ALREADY_INSTALLED`). Partial success is
+ * the designed outcome, not an error path — the UI reports per member.
+ */
+export interface PackInstallResultDto {
+    packId: string;
+    results: PackInstallMemberResultDto[];
+}
+/**
+ * `POST /api/extensions/scene/{sceneId}/template/install` (F15.8) — adopting a
+ * scene template's composition into the caller's own library.
+ *
+ * **The same per-member report as a pack, deliberately.** The Java record reuses
+ * `PackInstallMemberResultDto` verbatim (`SceneTemplateInstallResultDto`), because
+ * the act is identical — adopt a curated set, per member, never bypassing an ACL —
+ * and only the curation channel differs: a pack is a curated `extId` list, a scene
+ * template is a scene's E6 composition. A member the caller cannot see FAILs.
+ *
+ * Authored at the **W4 kickoff**, not by a session: `V15-095` asked for this pair
+ * at the W1 close and `V15-287` recorded at the W3 close that neither the Z5
+ * kickoff nor the orchestrator had made it, so the leg had shipped in W1 and gone
+ * two full waves with no frontend type, no fixture and no client. There is still
+ * **no UI caller** — that is a market-detail surface and no W4 session owns one.
+ */
+export interface SceneTemplateInstallResultDto {
+    sceneId: string;
+    results: PackInstallMemberResultDto[];
+}
+/** `POST`/`PUT /api/extensions/packs` — members given as an ordered `extId` list. */
+export interface PackUpsertRequest {
+    displayName: string;
+    summary?: string | null;
+    visibility: PackVisibility;
+    extIds: string[];
+}
+/**
+ * Which of F15.10's three static checks produced a finding.
+ *
+ * The list is closed on purpose: F15.10 names exactly three checks, and a
+ * reviewer UI that renders per-check sections needs to know the sections before
+ * a scan runs. A fourth check is a contract change, not a new string.
+ */
+export type ScanCheckId = "imports" | "secrets" | "permissions";
+/**
+ * **There is no blocking severity, and that is the contract, not an oversight.**
+ * F15.10 makes all three checks advisory — E4 human review stays the
+ * decision-maker, because a heuristic that blocks an upload gives a false
+ * positive no appeal path. The existing hard refusals (malformed manifest,
+ * oversized/malformed bundle) are unchanged and live nowhere near this type.
+ */
+export type ScanSeverity = "INFO" | "WARN";
+/**
+ * One scanner finding.
+ *
+ * `code` is the stable machine identity a UI keys its copy off; `message` is the
+ * server's English fallback for a code the client does not know. Render `code`
+ * when you have a translation, `message` when you do not — never concatenate.
+ */
+export interface ScanFindingDto {
+    check: ScanCheckId;
+    severity: ScanSeverity;
+    /**
+     * Stable, screaming-snake. The set ZB3 mints at W2:
+     * `IMPORT_NOT_ALLOWLISTED` · `EVAL_CALL` · `NEW_FUNCTION_CALL` ·
+     * `SECRET_PATTERN` · `SECRET_ENTROPY`. A client must tolerate an unknown code
+     * (render `message`) rather than narrow on this being exhaustive.
+     */
+    code: string;
+    message: string;
+    /** 1-based line in `bundle.mjs` when the finding is positional; `null` otherwise. */
+    line: number | null;
+    /**
+     * The offending specifier or a **redacted** excerpt — never the matched secret
+     * itself, and truncated server-side. A scan result is readable by every ADMIN
+     * reviewer, so it must not become a second place credentials live.
+     */
+    evidence: string | null;
+}
+/**
+ * Scope delta against the previous PUBLISHED version of the same extension —
+ * the reviewer blocker F15.10 exists to remove (today a scope-widening bump has
+ * to be caught by diffing two JSON bodies by hand).
+ *
+ * Computed server-side against **PUBLISHED** only: a DRAFT or REJECTED
+ * predecessor is not what users are running, so diffing against it would show a
+ * widening that never reached anyone.
+ */
+export interface ScanPermissionDiffDto {
+    /** `null` when no PUBLISHED predecessor exists — a first publish adds everything. */
+    previousVersion: string | null;
+    /** Scopes present now and not before. **The reviewer's actual signal.** */
+    added: string[];
+    removed: string[];
+    unchanged: string[];
+}
+/**
+ * The persisted scan payload: a JSONB column on `ngis_extension_version`,
+ * surfaced on {@link import("./extensions").ExtensionReviewQueueEntryDto}.
+ *
+ * **`completed: false` is not "clean".** The scanner runs inside the upload
+ * request and must never fail an upload it could not analyse, so a scanner error
+ * persists as `completed: false` with empty findings. A UI that renders that as
+ * a green check is asserting a result nobody obtained — show *not scanned*.
+ */
+export interface VersionScanResultDto {
+    /**
+     * Payload schema version. Present because these bytes are stored, not just
+     * transported: a row written by today's build is read by every later build,
+     * and a stored blob with no version is unmigratable.
+     */
+    schema: 1;
+    scannedAt: string;
+    completed: boolean;
+    /** Empty means the checks ran and found nothing — iff `completed` is `true`. */
+    findings: ScanFindingDto[];
+    /** `null` when the permission check itself did not run. */
+    permissionDiff: ScanPermissionDiffDto | null;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@ngis/plugin-sdk",
+  "version": "0.4.0",
+  "description": "Types-first SDK for authoring NeoGIS map plugins.",
+  "license": "Apache-2.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GeoScenarioScripter/NeoGIS-Frontend.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "homepage": "https://github.com/GeoScenarioScripter/NeoGIS-Frontend#readme",
+  "bugs": {
+    "url": "https://github.com/GeoScenarioScripter/NeoGIS-Frontend/issues"
+  },
+  "keywords": [
+    "neogis",
+    "gis",
+    "plugin",
+    "sdk"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build"
+  }
+}