@ai-matrx/associations 0.3.0 → 0.5.0

package/dist/core/index.d.cts

@@ -1,4 +1,4 @@
-import { EntityOverlayMap, EntityTypeToken, EntityOverlayEntry, ErrorSink, AssociationsRpcError, AssociationsDataSource, AssociationsIdentity, AssociationTargetType, AssociationsRpcResult, AssociationEdge, AssociationTargetEdge, AssociationSourceEdge, CategoryDimension, PlatformCategory, UserStateKind, UserEntityState, AssociationsEntry, CategoriesEntry, AssociationsConfig } from '../index.cjs';
+import { EntityOverlayMap, EntityTypeToken, EntityOverlayEntry, ErrorSink, AssociationsRpcError, AssociationsDataSource, AssociationsIdentity, AssociationTargetType, AssociationsRpcResult, AssociationEdge, AssociationTargetEdge, AssociationSourceEdge, CategoryDimension, PlatformCategory, UserStateKind, UserEntityState, PlatformComment, AssociationsEntry, CategoriesEntry, CommentsEntry, AssociationsConfig } from '../index.cjs';
 import 'react';
 
 /** The universal ownership column post-2026-reorg. */
@@ -474,6 +474,28 @@ interface AssociationHelpersApi {
 }
 declare function createAssociationHelpers(service: AssociationsServiceApi): AssociationHelpersApi;
 
+interface AddCommentArgs {
+    /** Registered entity-type token the comment hangs on (writes-strict, C18). */
+    entityType: string;
+    entityId: string;
+    body: string;
+    /** Reply target — an existing comment's id. Top-level when omitted. */
+    parentId?: string | null;
+    /** Org override; the RPC resolves task-org/personal-org when omitted. */
+    orgId?: string | null;
+}
+interface CommentsServiceApi {
+    listForEntity(entityType: string, entityId: string): Promise<AssociationsRpcResult<{
+        comments: PlatformComment[];
+    }>>;
+    add(args: AddCommentArgs): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    edit(id: string, body: string): Promise<AssociationsRpcResult<null>>;
+    remove(id: string): Promise<AssociationsRpcResult<null>>;
+}
+declare function createCommentsService(deps: CoreDeps): CommentsServiceApi;
+
 /** Cache key for one association endpoint. */
 declare function associationsKey(type: string, id: string): string;
 interface AssociationWriteResult {
@@ -488,6 +510,12 @@ interface CategoryMutationResult {
     id?: string;
     error?: string;
 }
+interface CommentMutationResult {
+    ok: boolean;
+    /** Set on a successful `addComment`. */
+    id?: string;
+    error?: string;
+}
 interface AssociationsStore {
     /** Stable, sync read of one endpoint's entry (idle default when uncached). */
     getEdges(type: string, id: string): AssociationsEntry;
@@ -531,7 +559,7 @@ interface AssociationsStore {
     }): Promise<AssociationWriteResult>;
     /** Reset one endpoint to idle and notify its subscribers. */
     invalidate(type: string, id: string): void;
-    /** Reset every association endpoint AND every category facet. */
+    /** Reset every association endpoint, category facet, and comment thread. */
     invalidateAll(): void;
     getCategories(dimension: CategoryDimension): CategoriesEntry;
     loadCategories(dimension: CategoryDimension, opts?: {
@@ -566,6 +594,41 @@ interface AssociationsStore {
         dimension: CategoryDimension;
         id: string;
     }): Promise<CategoryMutationResult>;
+    /** Stable, sync read of one entity's comment thread (idle when uncached). */
+    getComments(type: string, id: string): CommentsEntry;
+    /**
+     * Lazy load of every comment on `${type}:${id}` (oldest→newest; thread by
+     * `parentId`). Deduped per key; `status === "ready"` short-circuits unless
+     * `force`.
+     */
+    loadComments(type: string, id: string, opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    /** External-store contract for one entity's comment thread. */
+    subscribeComments(key: string, cb: () => void): () => void;
+    /** Post a comment (or a reply); on success force-reloads the thread. */
+    addComment(args: {
+        entityType: string;
+        entityId: string;
+        body: string;
+        parentId?: string | null;
+        orgId?: string | null;
+    }): Promise<CommentMutationResult>;
+    /** Edit a comment body (author-only in the RPC); reloads the thread. */
+    editComment(args: {
+        entityType: string;
+        entityId: string;
+        id: string;
+        body: string;
+    }): Promise<CommentMutationResult>;
+    /** Soft-delete a comment (author/org member in the RPC); reloads the thread. */
+    deleteComment(args: {
+        entityType: string;
+        entityId: string;
+        id: string;
+    }): Promise<CommentMutationResult>;
+    /** Reset one entity's comment thread to idle and notify its subscribers. */
+    invalidateComments(type: string, id: string): void;
     /** Batched title resolution + the session cache + prime. */
     titles: TitlesServiceApi;
     /** Per-user favorite/pinned/hidden state (`ues_*`). */
@@ -586,6 +649,7 @@ interface AssociationsStore {
     services: {
         associations: AssociationsServiceApi;
         categories: CategoriesServiceApi;
+        comments: CommentsServiceApi;
     };
     /** Merge more host overlay entries in (icons/routes/candidate loaders). */
     registerEntityOverlay: EntityRegistry["registerEntityOverlay"];
@@ -658,4 +722,22 @@ declare function isMembershipMetadata(metadata: unknown): boolean;
  */
 declare function isContentSourceEdge(sourceType: string, metadata?: unknown): boolean;
 
-export { type AddAssociationArgs, type AssertDemandedSchemaOptions, type AssociationGuards, type AssociationHelpersApi, type AssociationWriteResult, type AssociationsServiceApi, type AssociationsStore, type CandidateRecord, type CandidatesResult, type CandidatesServiceApi, type CategoriesServiceApi, type CategoryMutationResult, type ContainerRef, type ContentRole, type ConversationFileLink, type CoreDeps, type CreateEntityRowArgs, DEFAULT_ORG_COLUMN, DEFAULT_OWNER_COLUMN, type DemandedSchemaReport, type EdgeAttrs, type EdgeSpec, type EntityInfo, type EntityRef, type EntityRegistry, type EntityRowResult, type EntityRowsServiceApi, type FavoritesServiceApi, type ListCandidatesArgs, NON_CONTENT_SOURCE_TYPES, type PgErrorMapper, type RpcResultHelpers, SELF_TEST_MISSING_RPC, type SearchAcrossTokensArgs, type TitlesServiceApi, type UniversalCandidate, assertDemandedSchema, associationsKey, createAssociationGuards, createAssociationHelpers, createAssociationsService, createAssociationsStore, createCandidatesService, createCategoriesService, createEntityRegistry, createEntityRowsService, createFavoritesService, createRpcResultHelpers, createTitlesService, entityTitleCacheKey, err, firstError, isContentRole, isContentSourceEdge, isMembershipMetadata, isTransportFailure, isUuid, ok, resolveEntityToken };
+interface CategoryHierarchyItem {
+    category: PlatformCategory;
+    depth: 0 | 1;
+    parent: PlatformCategory | null;
+    displayName: string;
+}
+interface CategoryHierarchy {
+    items: CategoryHierarchyItem[];
+    roots: PlatformCategory[];
+    hasHierarchy: boolean;
+}
+/**
+ * Turns the RPC's ordered flat rows into the canonical two-level display order.
+ * Flat facets retain their exact input order. Invalid/orphaned rows remain
+ * visible at the root; the database guard prevents new ones from being made.
+ */
+declare function buildCategoryHierarchy(categories: PlatformCategory[]): CategoryHierarchy;
+
+export { type AddAssociationArgs, type AddCommentArgs, type AssertDemandedSchemaOptions, type AssociationGuards, type AssociationHelpersApi, type AssociationWriteResult, type AssociationsServiceApi, type AssociationsStore, type CandidateRecord, type CandidatesResult, type CandidatesServiceApi, type CategoriesServiceApi, type CategoryHierarchy, type CategoryHierarchyItem, type CategoryMutationResult, type CommentMutationResult, type CommentsServiceApi, type ContainerRef, type ContentRole, type ConversationFileLink, type CoreDeps, type CreateEntityRowArgs, DEFAULT_ORG_COLUMN, DEFAULT_OWNER_COLUMN, type DemandedSchemaReport, type EdgeAttrs, type EdgeSpec, type EntityInfo, type EntityRef, type EntityRegistry, type EntityRowResult, type EntityRowsServiceApi, type FavoritesServiceApi, type ListCandidatesArgs, NON_CONTENT_SOURCE_TYPES, type PgErrorMapper, type RpcResultHelpers, SELF_TEST_MISSING_RPC, type SearchAcrossTokensArgs, type TitlesServiceApi, type UniversalCandidate, assertDemandedSchema, associationsKey, buildCategoryHierarchy, createAssociationGuards, createAssociationHelpers, createAssociationsService, createAssociationsStore, createCandidatesService, createCategoriesService, createCommentsService, createEntityRegistry, createEntityRowsService, createFavoritesService, createRpcResultHelpers, createTitlesService, entityTitleCacheKey, err, firstError, isContentRole, isContentSourceEdge, isMembershipMetadata, isTransportFailure, isUuid, ok, resolveEntityToken };

package/dist/core/index.d.ts

@@ -1,4 +1,4 @@
-import { EntityOverlayMap, EntityTypeToken, EntityOverlayEntry, ErrorSink, AssociationsRpcError, AssociationsDataSource, AssociationsIdentity, AssociationTargetType, AssociationsRpcResult, AssociationEdge, AssociationTargetEdge, AssociationSourceEdge, CategoryDimension, PlatformCategory, UserStateKind, UserEntityState, AssociationsEntry, CategoriesEntry, AssociationsConfig } from '../index.js';
+import { EntityOverlayMap, EntityTypeToken, EntityOverlayEntry, ErrorSink, AssociationsRpcError, AssociationsDataSource, AssociationsIdentity, AssociationTargetType, AssociationsRpcResult, AssociationEdge, AssociationTargetEdge, AssociationSourceEdge, CategoryDimension, PlatformCategory, UserStateKind, UserEntityState, PlatformComment, AssociationsEntry, CategoriesEntry, CommentsEntry, AssociationsConfig } from '../index.js';
 import 'react';
 
 /** The universal ownership column post-2026-reorg. */
@@ -474,6 +474,28 @@ interface AssociationHelpersApi {
 }
 declare function createAssociationHelpers(service: AssociationsServiceApi): AssociationHelpersApi;
 
+interface AddCommentArgs {
+    /** Registered entity-type token the comment hangs on (writes-strict, C18). */
+    entityType: string;
+    entityId: string;
+    body: string;
+    /** Reply target — an existing comment's id. Top-level when omitted. */
+    parentId?: string | null;
+    /** Org override; the RPC resolves task-org/personal-org when omitted. */
+    orgId?: string | null;
+}
+interface CommentsServiceApi {
+    listForEntity(entityType: string, entityId: string): Promise<AssociationsRpcResult<{
+        comments: PlatformComment[];
+    }>>;
+    add(args: AddCommentArgs): Promise<AssociationsRpcResult<{
+        id: string;
+    }>>;
+    edit(id: string, body: string): Promise<AssociationsRpcResult<null>>;
+    remove(id: string): Promise<AssociationsRpcResult<null>>;
+}
+declare function createCommentsService(deps: CoreDeps): CommentsServiceApi;
+
 /** Cache key for one association endpoint. */
 declare function associationsKey(type: string, id: string): string;
 interface AssociationWriteResult {
@@ -488,6 +510,12 @@ interface CategoryMutationResult {
     id?: string;
     error?: string;
 }
+interface CommentMutationResult {
+    ok: boolean;
+    /** Set on a successful `addComment`. */
+    id?: string;
+    error?: string;
+}
 interface AssociationsStore {
     /** Stable, sync read of one endpoint's entry (idle default when uncached). */
     getEdges(type: string, id: string): AssociationsEntry;
@@ -531,7 +559,7 @@ interface AssociationsStore {
     }): Promise<AssociationWriteResult>;
     /** Reset one endpoint to idle and notify its subscribers. */
     invalidate(type: string, id: string): void;
-    /** Reset every association endpoint AND every category facet. */
+    /** Reset every association endpoint, category facet, and comment thread. */
     invalidateAll(): void;
     getCategories(dimension: CategoryDimension): CategoriesEntry;
     loadCategories(dimension: CategoryDimension, opts?: {
@@ -566,6 +594,41 @@ interface AssociationsStore {
         dimension: CategoryDimension;
         id: string;
     }): Promise<CategoryMutationResult>;
+    /** Stable, sync read of one entity's comment thread (idle when uncached). */
+    getComments(type: string, id: string): CommentsEntry;
+    /**
+     * Lazy load of every comment on `${type}:${id}` (oldest→newest; thread by
+     * `parentId`). Deduped per key; `status === "ready"` short-circuits unless
+     * `force`.
+     */
+    loadComments(type: string, id: string, opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    /** External-store contract for one entity's comment thread. */
+    subscribeComments(key: string, cb: () => void): () => void;
+    /** Post a comment (or a reply); on success force-reloads the thread. */
+    addComment(args: {
+        entityType: string;
+        entityId: string;
+        body: string;
+        parentId?: string | null;
+        orgId?: string | null;
+    }): Promise<CommentMutationResult>;
+    /** Edit a comment body (author-only in the RPC); reloads the thread. */
+    editComment(args: {
+        entityType: string;
+        entityId: string;
+        id: string;
+        body: string;
+    }): Promise<CommentMutationResult>;
+    /** Soft-delete a comment (author/org member in the RPC); reloads the thread. */
+    deleteComment(args: {
+        entityType: string;
+        entityId: string;
+        id: string;
+    }): Promise<CommentMutationResult>;
+    /** Reset one entity's comment thread to idle and notify its subscribers. */
+    invalidateComments(type: string, id: string): void;
     /** Batched title resolution + the session cache + prime. */
     titles: TitlesServiceApi;
     /** Per-user favorite/pinned/hidden state (`ues_*`). */
@@ -586,6 +649,7 @@ interface AssociationsStore {
     services: {
         associations: AssociationsServiceApi;
         categories: CategoriesServiceApi;
+        comments: CommentsServiceApi;
     };
     /** Merge more host overlay entries in (icons/routes/candidate loaders). */
     registerEntityOverlay: EntityRegistry["registerEntityOverlay"];
@@ -658,4 +722,22 @@ declare function isMembershipMetadata(metadata: unknown): boolean;
  */
 declare function isContentSourceEdge(sourceType: string, metadata?: unknown): boolean;
 
-export { type AddAssociationArgs, type AssertDemandedSchemaOptions, type AssociationGuards, type AssociationHelpersApi, type AssociationWriteResult, type AssociationsServiceApi, type AssociationsStore, type CandidateRecord, type CandidatesResult, type CandidatesServiceApi, type CategoriesServiceApi, type CategoryMutationResult, type ContainerRef, type ContentRole, type ConversationFileLink, type CoreDeps, type CreateEntityRowArgs, DEFAULT_ORG_COLUMN, DEFAULT_OWNER_COLUMN, type DemandedSchemaReport, type EdgeAttrs, type EdgeSpec, type EntityInfo, type EntityRef, type EntityRegistry, type EntityRowResult, type EntityRowsServiceApi, type FavoritesServiceApi, type ListCandidatesArgs, NON_CONTENT_SOURCE_TYPES, type PgErrorMapper, type RpcResultHelpers, SELF_TEST_MISSING_RPC, type SearchAcrossTokensArgs, type TitlesServiceApi, type UniversalCandidate, assertDemandedSchema, associationsKey, createAssociationGuards, createAssociationHelpers, createAssociationsService, createAssociationsStore, createCandidatesService, createCategoriesService, createEntityRegistry, createEntityRowsService, createFavoritesService, createRpcResultHelpers, createTitlesService, entityTitleCacheKey, err, firstError, isContentRole, isContentSourceEdge, isMembershipMetadata, isTransportFailure, isUuid, ok, resolveEntityToken };
+interface CategoryHierarchyItem {
+    category: PlatformCategory;
+    depth: 0 | 1;
+    parent: PlatformCategory | null;
+    displayName: string;
+}
+interface CategoryHierarchy {
+    items: CategoryHierarchyItem[];
+    roots: PlatformCategory[];
+    hasHierarchy: boolean;
+}
+/**
+ * Turns the RPC's ordered flat rows into the canonical two-level display order.
+ * Flat facets retain their exact input order. Invalid/orphaned rows remain
+ * visible at the root; the database guard prevents new ones from being made.
+ */
+declare function buildCategoryHierarchy(categories: PlatformCategory[]): CategoryHierarchy;
+
+export { type AddAssociationArgs, type AddCommentArgs, type AssertDemandedSchemaOptions, type AssociationGuards, type AssociationHelpersApi, type AssociationWriteResult, type AssociationsServiceApi, type AssociationsStore, type CandidateRecord, type CandidatesResult, type CandidatesServiceApi, type CategoriesServiceApi, type CategoryHierarchy, type CategoryHierarchyItem, type CategoryMutationResult, type CommentMutationResult, type CommentsServiceApi, type ContainerRef, type ContentRole, type ConversationFileLink, type CoreDeps, type CreateEntityRowArgs, DEFAULT_ORG_COLUMN, DEFAULT_OWNER_COLUMN, type DemandedSchemaReport, type EdgeAttrs, type EdgeSpec, type EntityInfo, type EntityRef, type EntityRegistry, type EntityRowResult, type EntityRowsServiceApi, type FavoritesServiceApi, type ListCandidatesArgs, NON_CONTENT_SOURCE_TYPES, type PgErrorMapper, type RpcResultHelpers, SELF_TEST_MISSING_RPC, type SearchAcrossTokensArgs, type TitlesServiceApi, type UniversalCandidate, assertDemandedSchema, associationsKey, buildCategoryHierarchy, createAssociationGuards, createAssociationHelpers, createAssociationsService, createAssociationsStore, createCandidatesService, createCategoriesService, createCommentsService, createEntityRegistry, createEntityRowsService, createFavoritesService, createRpcResultHelpers, createTitlesService, entityTitleCacheKey, err, firstError, isContentRole, isContentSourceEdge, isMembershipMetadata, isTransportFailure, isUuid, ok, resolveEntityToken };