@voltro/plugin-comments 0.84.0 → 0.86.0

package/THIRD-PARTY-NOTICES.md

@@ -1,70 +1,14 @@
 # Third-Party Notices — @voltro/plugin-comments
 
-This package depends on the open-source software listed below. Each is the
+This package uses the open-source software listed below. Each is the
 property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/plugin-comments itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (13 packages).
+Generated from the resolved runtime dependency closure (10 packages).
 
 ---
 
-## @effect/experimental@0.61.1
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2023-present The Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
-## @effect/sql@0.52.1
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2023-present The Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
 ## @tanstack/devtools-event-client@0.4.4
 
 License: MIT
@@ -233,34 +177,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## layerr@3.0.0
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2020 Perry Mitchell
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
 ## typeid-js@1.2.0
 
 License: Apache-2.0
@@ -469,14 +385,14 @@ Apache License
    limitations under the License.
 ```
 
-## ulidx@2.4.1
+## ulid@3.0.2
 
 License: MIT
 
 ```
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2021 Perry Mitchell
+Copyright (c) 2017 Alizain Feerasta
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
 import { Schema } from 'effect';
+import { YieldableError } from 'effect/Cause';
 
 /** The anchor's access check refused the caller — or no access rule is
  *  declared at all (fail-closed: undeclared access is a refusal, not a pass).
@@ -7,34 +8,39 @@ import { Schema } from 'effect';
  *  pointing here, and this is what they find — "no longer available", not a
  *  leak and not a crash. */
 export declare class CommentAccessRefused extends CommentAccessRefused_base {
+    get message(): string;
 }
 
-declare const CommentAccessRefused_base: Schema.TaggedErrorClass<CommentAccessRefused, "CommentAccessRefused", {
-    readonly _tag: Schema.tag<"CommentAccessRefused">;
-} & {
-    anchor: typeof Schema.String;
-    reason: typeof Schema.String;
-}>;
+declare const CommentAccessRefused_base: Schema.Class<CommentAccessRefused, Schema.TaggedStruct<"CommentAccessRefused", {
+    readonly anchor: Schema.String;
+    readonly reason: Schema.String;
+}>, YieldableError>;
 
 /** The thread / comment id resolves to nothing the caller may see. */
 export declare class CommentNotFound extends CommentNotFound_base {
 }
 
-declare const CommentNotFound_base: Schema.TaggedErrorClass<CommentNotFound, "CommentNotFound", {
-    readonly _tag: Schema.tag<"CommentNotFound">;
-} & {
-    id: typeof Schema.String;
-}>;
+declare const CommentNotFound_base: Schema.Class<CommentNotFound, Schema.TaggedStruct<"CommentNotFound", {
+    readonly id: Schema.String;
+}>, YieldableError>;
 
 /** Only the author edits or deletes their own comment (a `comments:moderate`
  *  scope overrides for delete). */
 export declare class CommentNotYours extends CommentNotYours_base {
 }
 
-declare const CommentNotYours_base: Schema.TaggedErrorClass<CommentNotYours, "CommentNotYours", {
-    readonly _tag: Schema.tag<"CommentNotYours">;
-} & {
-    id: typeof Schema.String;
-}>;
+declare const CommentNotYours_base: Schema.Class<CommentNotYours, Schema.TaggedStruct<"CommentNotYours", {
+    readonly id: Schema.String;
+}>, YieldableError>;
+
+/** The app's status policy (`statusPolicy`) refused resolving or reopening
+ *  this thread for the caller — the thread keeps its status. */
+export declare class CommentStatusRefused extends CommentStatusRefused_base {
+}
+
+declare const CommentStatusRefused_base: Schema.Class<CommentStatusRefused, Schema.TaggedStruct<"CommentStatusRefused", {
+    readonly threadId: Schema.String;
+    readonly reason: Schema.String;
+}>, YieldableError>;
 
 export { }

package/dist/errors.js

@@ -3,6 +3,13 @@ import { Schema as e } from "effect";
 var t = class extends e.TaggedError()("CommentAccessRefused", {
 	anchor: e.String,
 	reason: e.String
-}) {}, n = class extends e.TaggedError()("CommentNotFound", { id: e.String }) {}, r = class extends e.TaggedError()("CommentNotYours", { id: e.String }) {};
+}) {
+	get message() {
+		return this.reason;
+	}
+}, n = class extends e.TaggedError()("CommentNotFound", { id: e.String }) {}, r = class extends e.TaggedError()("CommentNotYours", { id: e.String }) {}, i = class extends e.TaggedError()("CommentStatusRefused", {
+	threadId: e.String,
+	reason: e.String
+}) {};
 //#endregion
-export { t as CommentAccessRefused, n as CommentNotFound, r as CommentNotYours };
+export { t as CommentAccessRefused, n as CommentNotFound, r as CommentNotYours, i as CommentStatusRefused };

package/dist/index.d.ts

@@ -5,6 +5,31 @@ import { ReactivityChannel } from '@voltro/protocol';
 import { Schema } from 'effect';
 import { Table } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+/**
+ * Remove the comments (with their reactions and read markers) of threads
+ * that have been resolved for longer than their kind's retention. The thread
+ * itself — anchor, passage, kind, status — and its status history stay, and
+ * the removal is appended to that history (actor `retention`, with the number
+ * of days), so a thread never disappears without a trace. A thread reopened
+ * since is not touched. Run it from a schedule over the root store (all
+ * tenants) or a request store (one tenant); a second run finds nothing new.
+ */
+export declare const applyCommentRetention: (store: DataStore, retention: CommentRetention, now?: Date) => Promise<{
+    readonly threads: number;
+    readonly comments: number;
+}>;
+
+/**
+ * What a thread is for. All three share the anchor and the same comments;
+ * the kind keeps them apart in the UI and in policy:
+ *  - `discussion` — talk about the anchored thing (the default);
+ *  - `note` — a standing editorial note (context for whoever edits next);
+ *  - `review` — the conversation of a review. A thread is never a task,
+ *    a suggestion or a decision; those live with their own owners.
+ */
+export declare const COMMENT_THREAD_KINDS: readonly ["discussion", "note", "review"];
 
 export declare interface CommentAccessInput {
     /** The thread's anchor, verbatim as the app wrote it. */
@@ -27,35 +52,30 @@ export declare interface CommentAccessInput {
  *  pointing here, and this is what they find — "no longer available", not a
  *  leak and not a crash. */
 export declare class CommentAccessRefused extends CommentAccessRefused_base {
+    get message(): string;
 }
 
-declare const CommentAccessRefused_base: Schema.TaggedErrorClass<CommentAccessRefused, "CommentAccessRefused", {
-    readonly _tag: Schema.tag<"CommentAccessRefused">;
-} & {
-    anchor: typeof Schema.String;
-    reason: typeof Schema.String;
-}>;
+declare const CommentAccessRefused_base: Schema.Class<CommentAccessRefused, Schema.TaggedStruct<"CommentAccessRefused", {
+    readonly anchor: Schema.String;
+    readonly reason: Schema.String;
+}>, YieldableError>;
 
 /** The thread / comment id resolves to nothing the caller may see. */
 export declare class CommentNotFound extends CommentNotFound_base {
 }
 
-declare const CommentNotFound_base: Schema.TaggedErrorClass<CommentNotFound, "CommentNotFound", {
-    readonly _tag: Schema.tag<"CommentNotFound">;
-} & {
-    id: typeof Schema.String;
-}>;
+declare const CommentNotFound_base: Schema.Class<CommentNotFound, Schema.TaggedStruct<"CommentNotFound", {
+    readonly id: Schema.String;
+}>, YieldableError>;
 
 /** Only the author edits or deletes their own comment (a `comments:moderate`
  *  scope overrides for delete). */
 export declare class CommentNotYours extends CommentNotYours_base {
 }
 
-declare const CommentNotYours_base: Schema.TaggedErrorClass<CommentNotYours, "CommentNotYours", {
-    readonly _tag: Schema.tag<"CommentNotYours">;
-} & {
-    id: typeof Schema.String;
-}>;
+declare const CommentNotYours_base: Schema.Class<CommentNotYours, Schema.TaggedStruct<"CommentNotYours", {
+    readonly id: Schema.String;
+}>, YieldableError>;
 
 export declare interface CommentQuote {
     /** The selected text. */
@@ -80,6 +100,10 @@ export declare const commentReadsTable: Table<"_voltro_comment_reads", FieldDefi
     readonly lastReadAt: ColumnBuilder<Date, "timestamp", boolean>;
 }>, true, never>;
 
+/** How long the comments of a resolved thread are kept, in days, per kind.
+ *  A kind left out keeps its comments. */
+export declare type CommentRetention = Partial<Readonly<Record<CommentThreadKind, number>>>;
+
 /** One push channel for the whole surface: every comment write publishes, and
  *  `comments.list` re-runs for subscribers. Table-granular by design for now —
  *  the read-set work (plan 01 P3) is the named narrowing. */
@@ -112,6 +136,21 @@ declare interface CommentsPluginOptions {
      * the caller's tenant unless `crossTenant: true` is set — the seam is
      * tenant-safe by construction, not by every implementor remembering.
      */
+    /**
+     * Who may resolve or reopen a thread, on top of the anchor access rule —
+     * say, only a publisher reopens a resolved review thread. Answer false to
+     * refuse (`CommentStatusRefused`); a throw refuses too. Absent: anyone who
+     * may read the anchor. Allowed or not, nothing changes silently — every
+     * change is recorded in `_voltro_comment_thread_events`.
+     */
+    readonly statusPolicy?: (input: CommentStatusInput) => Promise<boolean>;
+    /**
+     * Which threads a caller sees, on top of the anchor access rule — say,
+     * editorial notes only for the team. A hidden thread is absent from
+     * `comments.list` and refuses replies and status changes like a missing
+     * one. Absent: every thread on a readable anchor.
+     */
+    readonly visibleTo?: (input: CommentVisibilityInput) => boolean;
     readonly resolveMentions?: (input: MentionSearchInput) => Promise<ReadonlyArray<{
         readonly subjectId: string;
         readonly label: string;
@@ -141,6 +180,48 @@ export declare const commentsTable: Table<"_voltro_comments", FieldDefinitions<{
     readonly tenantId: ColumnBuilder<string | null, "text", boolean>;
 }>, true, "byCommentThread">;
 
+export declare interface CommentStatusInput {
+    readonly thread: CommentThreadFacts;
+    readonly to: 'open' | 'resolved';
+    readonly subject: CommentAccessInput['subject'];
+    readonly store: DataStore | undefined;
+}
+
+/** The app's status policy (`statusPolicy`) refused resolving or reopening
+ *  this thread for the caller — the thread keeps its status. */
+export declare class CommentStatusRefused extends CommentStatusRefused_base {
+}
+
+declare const CommentStatusRefused_base: Schema.Class<CommentStatusRefused, Schema.TaggedStruct<"CommentStatusRefused", {
+    readonly threadId: Schema.String;
+    readonly reason: Schema.String;
+}>, YieldableError>;
+
+/** Every status change of a thread — who opened, resolved or reopened it,
+ *  when, and why. Append-only: nothing here is updated or deleted. */
+export declare const commentThreadEventsTable: Table<"_voltro_comment_thread_events", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly threadId: ColumnBuilder<string, "text", boolean>;
+    /** null for the opening. */
+    readonly fromStatus: ColumnBuilder<string | null, "text", boolean>;
+    readonly toStatus: ColumnBuilder<string, "text", boolean>;
+    readonly actor: ColumnBuilder<string, "text", boolean>;
+    readonly reason: ColumnBuilder<string | null, "text", boolean>;
+    readonly at: ColumnBuilder<Date, "timestamp", true>;
+    readonly tenantId: ColumnBuilder<string | null, "text", boolean>;
+}>, true, "byThreadEvents">;
+
+/** A thread as the app's status and visibility rules see it. */
+export declare interface CommentThreadFacts {
+    readonly id: string;
+    readonly anchor: string;
+    readonly kind: CommentThreadKind;
+    readonly status: 'open' | 'resolved';
+    readonly createdBy: string;
+}
+
+export declare type CommentThreadKind = (typeof COMMENT_THREAD_KINDS)[number];
+
 export declare const commentThreadsTable: Table<"_voltro_comment_threads", FieldDefinitions<{
     readonly id: ColumnBuilder<string, "id", boolean>;
     /** Free string key (`order:123`, `doc:abc#section-2`) — the app decides the
@@ -148,12 +229,19 @@ export declare const commentThreadsTable: Table<"_voltro_comment_threads", Field
     readonly anchor: ColumnBuilder<string, "text", boolean>;
     /** The selected passage the thread is about (`./quote`), or null. */
     readonly quote: ColumnBuilder<CommentQuote | null, "json", boolean>;
+    /** `discussion` | `note` | `review` (`./rpc` COMMENT_THREAD_KINDS). */
+    readonly kind: ColumnBuilder<string, "text", true>;
     readonly status: ColumnBuilder<string, "text", true>;
     readonly createdBy: ColumnBuilder<string, "text", boolean>;
     readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
     readonly tenantId: ColumnBuilder<string | null, "text", boolean>;
 }>, true, "byThreadAnchor">;
 
+export declare interface CommentVisibilityInput {
+    readonly thread: CommentThreadFacts;
+    readonly subject: CommentAccessInput['subject'];
+}
+
 /**
  * Where `quote` stands in `text` now: `{ start, end }`, or null when the text
  * no longer holds the passage. With the passage more than once, the one whose