@agent-native/core 0.227.0 → 0.228.0-nightly-20261111004142

package/dist/review/registry.d.ts

@@ -1,9 +1,59 @@
+import type { DbExec } from "../db/client.js";
 import { type Visibility } from "../sharing/schema.js";
-import type { ReviewResourceAccess, ReviewResourceContext, ReviewResourceRole, ReviewableResourceRegistration } from "./types.js";
+import type { ReviewCommentPolicy, ReviewCommentWriteEvent, ReviewResourceAccess, ReviewResourceContext, ReviewResourceRole, ReviewableResourceRegistration } from "./types.js";
 export declare function registerReviewableResource(registration: ReviewableResourceRegistration): void;
 export declare function getReviewableResource(type: string): ReviewableResourceRegistration | undefined;
 export declare function listReviewableResources(): ReviewableResourceRegistration[];
 export declare function resolveReviewableResourceAccess(resourceType: string, resourceId: string, ctx?: ReviewResourceContext): Promise<ReviewResourceAccess | null>;
 export declare function assertReviewableResourceAccess(resourceType: string, resourceId: string, ctx: ReviewResourceContext | undefined, minimumRole: ReviewResourceRole): Promise<ReviewResourceAccess>;
+/** The resource's comment policy, with the kit's defaults filled in. */
+export declare function reviewCommentPolicy(resourceType: string): Required<ReviewCommentPolicy>;
+/**
+ * The role a suggestion's author needs. A suggestion opens a comment thread,
+ * so a resource asking more of commenters asks it of suggesters too; but it
+ * proposes a change as well, so it never takes less than a commenter, even
+ * where viewers may comment.
+ */
+export declare function reviewSuggestionAuthorRole(resourceType: string): ReviewResourceRole;
+/**
+ * Whether this access lets its holder comment, reply and react, and edit or
+ * delete their own comments. A viewer-level policy opens that to signed-in
+ * viewers only: a caller who isn't signed in, such as a visitor to a public
+ * resource, still needs the commenter role.
+ */
+export declare function canCommentOnReviewableResource(resourceType: string, access: ReviewResourceAccess | null | undefined, signedIn?: boolean): access is ReviewResourceAccess;
+/** Checks the caller holds at least the role the comment policy asks for. */
+export declare function assertReviewCommentAccess(resourceType: string, resourceId: string, ctx: ReviewResourceContext | undefined): Promise<ReviewResourceAccess>;
+/**
+ * The kit's own anchor kind, on the thread a suggestion opens: the anchors of
+ * its operations, in order. Every resource accepts it, and none may declare it.
+ */
+export declare const REVIEW_SUGGESTION_ANCHOR_KIND = "review-suggestion";
+export interface ReviewAnchorInput {
+    anchor?: unknown;
+    anchorKind?: string | null;
+    anchorVersion?: number | null;
+}
+export interface NormalizedReviewAnchor {
+    anchor: unknown;
+    anchorKind: string | null;
+    anchorVersion: number | null;
+}
+/**
+ * Checks a comment's anchor against its resource's anchor kinds and returns it
+ * as it's stored. A resource that declares no kinds keeps untyped anchors, as
+ * before kinds existed; one that declares any needs every anchor to name one.
+ */
+export declare function normalizeReviewAnchor(resourceType: string, input: ReviewAnchorInput): NormalizedReviewAnchor;
+/**
+ * Refuses a person's comment write that names one of the kit's own anchor
+ * kinds, or moves an anchor that keeps one. Only the kit writes those, so a
+ * resource's own parser reads every anchor a person sends.
+ */
+export declare function assertPersonReviewAnchorKind(anchorKind: string | null | undefined): void;
+/** Whether a resource type has a hook that comment writes must run. */
+export declare function hasReviewCommentWriteHook(resourceType: string): boolean;
+/** Runs the resource's comment write hook on the write's own transaction. */
+export declare function runReviewCommentWriteHook(resourceType: string, event: ReviewCommentWriteEvent, tx: DbExec): Promise<void>;
 export declare function normalizeReviewVisibility(visibility: Visibility | null | undefined): Visibility;
 export declare function __resetReviewableResourcesForTests(): void;

package/dist/review/registry.js

@@ -1,11 +1,20 @@
 import { ForbiddenError, resolveAccess, } from "../sharing/access.js";
 import { getShareableResource } from "../sharing/registry.js";
 import { roleSatisfies } from "../sharing/schema.js";
+import { ReviewAnchorError } from "./errors.js";
 const registrations = new Map();
 export function registerReviewableResource(registration) {
     if (!registration.type.trim()) {
         throw new Error("registerReviewableResource requires a non-empty resource type");
     }
+    for (const [name, kind] of Object.entries(registration.anchorKinds ?? {})) {
+        if (!name.trim() || !Number.isInteger(kind.version) || kind.version < 1) {
+            throw new Error(`Anchor kind "${name}" on ${registration.type} needs a name and a whole version from 1`);
+        }
+        if (ownAnchorKind(KIT_ANCHOR_KINDS, name)) {
+            throw new Error(`Anchor kind "${name}" belongs to the review kit`);
+        }
+    }
     registrations.set(registration.type, registration);
 }
 export function getReviewableResource(type) {
@@ -50,6 +59,114 @@ export async function assertReviewableResourceAccess(resourceType, resourceId, c
     }
     return access;
 }
+/** The resource's comment policy, with the kit's defaults filled in. */
+export function reviewCommentPolicy(resourceType) {
+    const policy = getReviewableResource(resourceType)?.comments;
+    return {
+        minimumRole: policy?.minimumRole ?? "commenter",
+        unmentionedRoute: policy?.unmentionedRoute ?? "agent",
+    };
+}
+/**
+ * The role a suggestion's author needs. A suggestion opens a comment thread,
+ * so a resource asking more of commenters asks it of suggesters too; but it
+ * proposes a change as well, so it never takes less than a commenter, even
+ * where viewers may comment.
+ */
+export function reviewSuggestionAuthorRole(resourceType) {
+    const { minimumRole } = reviewCommentPolicy(resourceType);
+    return roleSatisfies(minimumRole, "commenter") ? minimumRole : "commenter";
+}
+/**
+ * Whether this access lets its holder comment, reply and react, and edit or
+ * delete their own comments. A viewer-level policy opens that to signed-in
+ * viewers only: a caller who isn't signed in, such as a visitor to a public
+ * resource, still needs the commenter role.
+ */
+export function canCommentOnReviewableResource(resourceType, access, signedIn = true) {
+    return Boolean(access &&
+        roleSatisfies(access.role, reviewCommentPolicy(resourceType).minimumRole) &&
+        (signedIn || roleSatisfies(access.role, "commenter")));
+}
+/** Checks the caller holds at least the role the comment policy asks for. */
+export async function assertReviewCommentAccess(resourceType, resourceId, ctx) {
+    const access = await resolveReviewableResourceAccess(resourceType, resourceId, ctx);
+    if (!canCommentOnReviewableResource(resourceType, access, Boolean(ctx?.userEmail))) {
+        throw new ForbiddenError(`Not allowed to comment on ${resourceType}:${resourceId}`);
+    }
+    return access;
+}
+/**
+ * The kit's own anchor kind, on the thread a suggestion opens: the anchors of
+ * its operations, in order. Every resource accepts it, and none may declare it.
+ */
+export const REVIEW_SUGGESTION_ANCHOR_KIND = "review-suggestion";
+const KIT_ANCHOR_KINDS = {
+    [REVIEW_SUGGESTION_ANCHOR_KIND]: { version: 1, parse: (anchor) => anchor },
+};
+function ownAnchorKind(kinds, name) {
+    const kind = kinds?.[name];
+    return kind && Object.prototype.hasOwnProperty.call(kinds, name)
+        ? kind
+        : null;
+}
+/**
+ * Checks a comment's anchor against its resource's anchor kinds and returns it
+ * as it's stored. A resource that declares no kinds keeps untyped anchors, as
+ * before kinds existed; one that declares any needs every anchor to name one.
+ */
+export function normalizeReviewAnchor(resourceType, input) {
+    const anchor = input.anchor ?? null;
+    const kinds = getReviewableResource(resourceType)?.anchorKinds;
+    const kindName = input.anchorKind ?? null;
+    if (kindName === null) {
+        if (input.anchorVersion != null) {
+            throw new ReviewAnchorError("An anchor version needs an anchor kind.");
+        }
+        if (anchor !== null && kinds && Object.keys(kinds).length > 0) {
+            throw new ReviewAnchorError(`Anchored ${resourceType} comments need an anchor kind: ${Object.keys(kinds).join(", ")}.`);
+        }
+        return { anchor, anchorKind: null, anchorVersion: null };
+    }
+    const kind = ownAnchorKind(KIT_ANCHOR_KINDS, kindName) ?? ownAnchorKind(kinds, kindName);
+    if (!kind) {
+        throw new ReviewAnchorError(`${resourceType} comments have no anchor kind "${kindName}".`);
+    }
+    const version = input.anchorVersion ?? kind.version;
+    if (!Number.isInteger(version) || version < 1 || version > kind.version) {
+        throw new ReviewAnchorError(`Anchor kind "${kindName}" has no version ${version}; the latest is ${kind.version}.`);
+    }
+    let parsed;
+    try {
+        parsed = kind.parse(anchor, version);
+    }
+    catch (error) {
+        throw new ReviewAnchorError(`Not a valid "${kindName}" anchor: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return {
+        anchor: parsed === undefined ? null : parsed,
+        anchorKind: kindName,
+        anchorVersion: version,
+    };
+}
+/**
+ * Refuses a person's comment write that names one of the kit's own anchor
+ * kinds, or moves an anchor that keeps one. Only the kit writes those, so a
+ * resource's own parser reads every anchor a person sends.
+ */
+export function assertPersonReviewAnchorKind(anchorKind) {
+    if (anchorKind != null && ownAnchorKind(KIT_ANCHOR_KINDS, anchorKind)) {
+        throw new ReviewAnchorError(`Only the review kit writes "${anchorKind}" anchors.`);
+    }
+}
+/** Whether a resource type has a hook that comment writes must run. */
+export function hasReviewCommentWriteHook(resourceType) {
+    return Boolean(getReviewableResource(resourceType)?.onCommentWrite);
+}
+/** Runs the resource's comment write hook on the write's own transaction. */
+export async function runReviewCommentWriteHook(resourceType, event, tx) {
+    await getReviewableResource(resourceType)?.onCommentWrite?.(event, tx);
+}
 export function normalizeReviewVisibility(visibility) {
     return visibility === "org" || visibility === "public"
         ? visibility

package/dist/review/store.d.ts

@@ -1,6 +1,6 @@
 import { type DbExec } from "../db/client.js";
 import type { Visibility } from "../sharing/schema.js";
-import type { ReviewActorKind, ReviewComment, ReviewCommentKind, ReviewCommentReaction, ReviewThreadPreference, ReviewMention, ReviewResolutionTarget, ReviewScope, ReviewStatus, ReviewStatusEntry } from "./types.js";
+import type { ReviewActorKind, ReviewComment, ReviewCommentKind, ReviewCommentLink, ReviewCommentReaction, ReviewThreadPreference, ReviewMention, ReviewResolutionTarget, ReviewScope, ReviewStatus, ReviewStatusEntry } from "./types.js";
 type ReviewThreadStatus = "open" | "resolved";
 export interface InsertReviewCommentInput {
     id?: string;
@@ -9,8 +9,11 @@ export interface InsertReviewCommentInput {
     threadId?: string | null;
     parentCommentId?: string | null;
     targetId?: string | null;
+    surfaceId?: string | null;
     kind?: ReviewCommentKind;
     anchor?: unknown;
+    anchorKind?: string | null;
+    anchorVersion?: number | null;
     body: string;
     authorEmail?: string | null;
     authorName?: string | null;
@@ -30,21 +33,47 @@ export interface InsertReviewCommentResult {
 export interface UpdateReviewCommentInput {
     body?: string;
     anchor?: unknown;
+    /** With `anchor`: a new kind for it. Left out, the comment's kind stays. */
+    anchorKind?: string | null;
+    anchorVersion?: number | null;
     mentions?: ReviewMention[];
 }
+export interface ReviewCommentWriteOptions {
+    /**
+     * The revision the caller read. When the comment has moved past it, nothing
+     * is written and a `ReviewCommentRevisionConflictError` is thrown.
+     */
+    expectedRevision?: number | undefined;
+    /** Who made the change, for the resource's write hook. */
+    actorEmail?: string | null | undefined;
+}
 export interface QueryReviewCommentsInput {
     resourceType: string;
     resourceId: string;
     scope: ReviewScope;
-    bypassScope?: boolean;
-    includeResolved?: boolean;
-    includeDeleted?: boolean;
-    targetId?: string | null;
-    newestFirst?: boolean;
+    bypassScope?: boolean | undefined;
+    includeResolved?: boolean | undefined;
+    includeDeleted?: boolean | undefined;
+    targetId?: string | null | undefined;
+    /** One surface's comments, or with `null` those on no surface. */
+    surfaceId?: string | null | undefined;
+    newestFirst?: boolean | undefined;
     rootOnly?: boolean;
     resolutionTargets?: readonly (ReviewResolutionTarget | null)[];
     unconsumedOnly?: boolean;
-    limit?: number;
+    /** Oldest first only: start after this comment. */
+    after?: ReviewCommentPosition | undefined;
+    limit?: number | undefined;
+}
+/** Where a comment sits in oldest-first order. */
+export interface ReviewCommentPosition {
+    createdAt: string;
+    id: string;
+}
+export interface ReviewCommentPage {
+    comments: ReviewComment[];
+    /** Pass back as `cursor` for the next page; null on the last one. */
+    nextCursor: string | null;
 }
 export interface GetReviewThreadSummaryInput {
     resourceType: string;
@@ -52,6 +81,8 @@ export interface GetReviewThreadSummaryInput {
     scope: ReviewScope;
     bypassScope?: boolean;
     targetId?: string | null;
+    /** One surface's threads, or `null` for those on no surface. */
+    surfaceId?: string | null | undefined;
 }
 export interface ReviewThreadSummary {
     openCount: number;
@@ -152,6 +183,14 @@ export declare function insertReviewReplyIdempotently(input: InsertReviewComment
 }): Promise<InsertReviewCommentResult>;
 export declare function insertReviewCommentWithClient(input: InsertReviewCommentInput, client: DbExec): Promise<ReviewComment>;
 export declare function queryReviewComments(input: QueryReviewCommentsInput): Promise<ReviewComment[]>;
+/**
+ * One page of a resource's comments, oldest first, and the cursor for the
+ * next. Unlike a plain list, which stops at its limit, every comment is
+ * reachable page by page.
+ */
+export declare function queryReviewCommentPage(input: Omit<QueryReviewCommentsInput, "after"> & {
+    cursor?: string | null | undefined;
+}): Promise<ReviewCommentPage>;
 export declare function getReviewThreadSummary(input: GetReviewThreadSummaryInput): Promise<ReviewThreadSummary>;
 export declare function getReviewCommentById(id: string, scope: ReviewScope, options?: {
     bypassScope?: boolean;
@@ -162,12 +201,6 @@ export declare function getReviewThreadRoot(threadId: string, resource: {
 }, scope: ReviewScope, options?: {
     bypassScope?: boolean;
 }): Promise<ReviewComment | null>;
-export declare function updateReviewCommentAnchor(input: {
-    commentId: string;
-    resourceType: string;
-    resourceId: string;
-    anchor: unknown;
-}): Promise<number>;
 export declare function resolveReviewThread(threadId: string, resolvedBy?: string | null, resource?: {
     resourceType: string;
     resourceId: string;
@@ -218,7 +251,7 @@ export declare function listReviewThreadParticipantEmails(input: {
 export declare function updateReviewComment(id: string, input: UpdateReviewCommentInput, resource?: {
     resourceType: string;
     resourceId: string;
-}): Promise<ReviewComment | null>;
+}, options?: ReviewCommentWriteOptions): Promise<ReviewComment | null>;
 export declare function consumeReviewFeedback(ids: string[], consumedAt?: string, resource?: {
     resourceType: string;
     resourceId: string;
@@ -227,6 +260,18 @@ export declare function upsertReviewStatus(input: UpsertReviewStatusInput): Prom
 export declare function getReviewStatus(resourceType: string, resourceId: string, scope: ReviewScope, options?: {
     bypassScope?: boolean;
 }): Promise<ReviewStatusEntry | null>;
+/**
+ * Links a comment to the same comment or thread in another system, such as a
+ * Notion comment or discussion, so an import can skip what it already copied.
+ * Linking the same outside ID to the same comment again changes nothing;
+ * linking it to another comment is refused. Links outlive a deleted comment,
+ * so a later import doesn't bring it back.
+ */
+export declare function linkReviewComment(input: Omit<ReviewCommentLink, "createdAt" | "resourceType" | "resourceId">, client?: DbExec): Promise<ReviewCommentLink>;
+/** The comment an outside ID is linked to, if any. */
+export declare function findReviewCommentLink(input: Pick<ReviewCommentLink, "provider" | "externalKind" | "externalId">, client?: DbExec): Promise<ReviewCommentLink | null>;
+/** Every outside link on these comments, optionally from one system. */
+export declare function listReviewCommentLinks(commentIds: readonly string[], provider?: string): Promise<ReviewCommentLink[]>;
 export declare function __resetReviewInitForTests(): void;
 export declare function reviewCommentIdForClientOperation(clientOperationId: string): string;
 export {};