@majikah/majik-message 0.2.21 → 0.3.0

package/dist/core/contacts/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class MajikContactManagerError extends Error {
+    cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare class MajikContactDirectoryError extends Error {
+    cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare class MajikContactGroupManagerError extends Error {
+    cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}

package/dist/core/contacts/errors.js

@@ -0,0 +1,27 @@
+/* -------------------------------
+ * Errors
+ * ------------------------------- */
+export class MajikContactManagerError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "MajikContactManagerError";
+        this.cause = cause;
+    }
+}
+export class MajikContactDirectoryError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "MajikContactDirectoryError";
+        this.cause = cause;
+    }
+}
+export class MajikContactGroupManagerError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "MajikContactGroupManagerError";
+        this.cause = cause;
+    }
+}

package/dist/core/contacts/majik-contact-directory.d.ts

@@ -1,13 +1,7 @@
 import { MessageEnvelope } from "../messages/message-envelope";
 import { MAJIK_API_RESPONSE } from "../types";
-import { MajikContact, MajikContactData, SerializedMajikContact } from "@majikah/majik-contact";
-export interface MajikContactDirectoryData {
-    contacts: SerializedMajikContact[];
-}
-export declare class MajikContactDirectoryError extends Error {
-    cause?: unknown;
-    constructor(message: string, cause?: unknown);
-}
+import { MajikContact, MajikContactData } from "@majikah/majik-contact";
+import { MajikContactDirectoryData } from "./types";
 export declare class MajikContactDirectory {
     private contacts;
     private fingerprintMap;

package/dist/core/contacts/majik-contact-directory.js

@@ -1,17 +1,7 @@
 import { KEY_ALGO } from "../crypto/constants";
 import { base64ToArrayBuffer } from "../utils/utilities";
 import { MajikContact, } from "@majikah/majik-contact";
-/* -------------------------------
- * Errors
- * ------------------------------- */
-export class MajikContactDirectoryError extends Error {
-    cause;
-    constructor(message, cause) {
-        super(message);
-        this.name = "MajikContactDirectoryError";
-        this.cause = cause;
-    }
-}
+import { MajikContactDirectoryError } from "./errors";
 /* -------------------------------
  * MajikContactDirectory Class
  * ------------------------------- */

package/dist/core/contacts/majik-contact-groups.d.ts

@@ -0,0 +1,185 @@
+import { MajikContact, MajikContactGroup, MajikContactGroupMeta } from "@majikah/majik-contact";
+import { MajikContactDirectory } from "./majik-contact-directory";
+import { MAJIK_API_RESPONSE } from "../types";
+import { MajikContactGroupManagerData } from "./types";
+/**
+ * Manages the full lifecycle of MajikContactGroup instances.
+ *
+ * Responsibilities:
+ *  - Owns the canonical Map of all groups (user-created + system groups)
+ *  - Maintains a reverse index: contactId → Set<groupId> for O(1) group lookups per contact
+ *  - Hydrates group members into full MajikContact instances via an injected MajikContactDirectory
+ *  - Automatically syncs system group side-effects (e.g. Blocked group ↔ MajikContact.block())
+ *  - Provides a handleContactRemoved() hook for MajikContactDirectory to call on contact removal
+ *  - Handles serialization / deserialization of all groups together
+ *
+ * System groups (Favorites, Blocked) are always present and are bootstrapped in the constructor.
+ * They cannot be deleted or renamed but their membership is fully manageable.
+ */
+export declare class MajikContactGroupManager {
+    private groups;
+    /**
+     * Reverse index: contactId → Set of groupIds the contact belongs to.
+     * Kept in sync on every membership mutation so getGroupsForContact() is O(1).
+     */
+    private contactGroupIndex;
+    private directory;
+    constructor(directory: MajikContactDirectory);
+    /**
+     * Ensures the two system groups always exist on construction.
+     * Safe to call multiple times — skips if already present.
+     */
+    private bootstrapSystemGroups;
+    /**
+     * Creates and registers a new user group.
+     * Throws if a group with the same ID already exists.
+     */
+    createGroup(id: string, name: string, meta?: Partial<Omit<MajikContactGroupMeta, "name">>, initialMemberIds?: string[]): MajikContactGroup;
+    /**
+     * Registers an already-constructed MajikContactGroup instance.
+     * Useful when importing groups from external sources.
+     * Throws if a group with the same ID already exists.
+     */
+    addGroup(group: MajikContactGroup): this;
+    /**
+     * Removes a user group by ID.
+     * System groups cannot be deleted.
+     * Cleans up the reverse index for all former members.
+     */
+    removeGroup(id: string): MAJIK_API_RESPONSE;
+    getGroup(id: string): MajikContactGroup | undefined;
+    getGroupOrThrow(id: string): MajikContactGroup;
+    hasGroup(id: string): boolean;
+    /**
+     * Returns all groups, optionally filtered and/or sorted.
+     *
+     * @param includeSystem  Include system groups (Favorites, Blocked). Default: true.
+     * @param sortedByName   Sort results by group name. Default: false.
+     */
+    listGroups(includeSystem?: boolean, sortedByName?: boolean): MajikContactGroup[];
+    /**
+     * Updates mutable metadata fields on a group.
+     * Name is protected on system groups (delegates to MajikContactGroup.updateName which throws).
+     */
+    updateGroupMeta(id: string, meta: Partial<Pick<MajikContactGroupMeta, "name" | "description">>): MajikContactGroup;
+    /**
+     * Adds a contact to a group.
+     *
+     * - Validates the contact exists in the directory.
+     * - If the target group is the system Blocked group, also calls contact.block()
+     *   on the directory to keep MajikContact state in sync.
+     * - Throws if the contact is already a member (strict — use addMemberIfAbsent for idempotent).
+     */
+    addContactToGroup(groupId: string, contactId: string): MajikContactGroup;
+    /**
+     * Idempotent variant — does not throw if the contact is already a member.
+     * Still validates contact existence and handles Blocked sync.
+     */
+    addContactToGroupIfAbsent(groupId: string, contactId: string): MajikContactGroup;
+    /**
+     * Adds multiple contacts to a group in one call.
+     * All contacts are validated before any mutation is applied (all-or-nothing).
+     */
+    addContactsToGroup(groupId: string, contactIds: string[]): MajikContactGroup;
+    /**
+     * Removes a contact from a group.
+     *
+     * - If removing from the system Blocked group, also calls contact.unblock()
+     *   to keep MajikContact state in sync.
+     * - Throws if the contact is not a member (strict — use removeContactFromGroupIfPresent for idempotent).
+     */
+    removeContactFromGroup(groupId: string, contactId: string): MajikContactGroup;
+    /**
+     * Idempotent variant — does not throw if the contact is not a member.
+     */
+    removeContactFromGroupIfPresent(groupId: string, contactId: string): MajikContactGroup;
+    /**
+     * Moves a contact from one group to another atomically.
+     * Throws if the contact is not a member of the source group.
+     */
+    moveContact(contactId: string, fromGroupId: string, toGroupId: string): void;
+    /**
+     * Returns all group IDs the contact belongs to.
+     * O(1) — backed by the reverse index.
+     */
+    getGroupIdsForContact(contactId: string): string[];
+    /**
+     * Returns all groups the contact belongs to as MajikContactGroup instances.
+     */
+    getGroupsForContact(contactId: string): MajikContactGroup[];
+    /**
+     * Returns all hydrated MajikContact instances that are members of the given group.
+     * Contacts that exist in the group but have been removed from the directory are silently skipped.
+     */
+    getContactsInGroup(groupId: string): MajikContact[];
+    /**
+     * Returns hydrated contacts that are members of the given group,
+     * sorted by their display label (or ID if no label set).
+     */
+    getContactsInGroupSorted(groupId: string): MajikContact[];
+    /**
+     * Returns true if the contact is a member of the given group.
+     */
+    isContactInGroup(groupId: string, contactId: string): boolean;
+    /**
+     * Returns true if the contact is in the system Favorites group.
+     */
+    isFavorite(contactId: string): boolean;
+    /**
+     * Returns true if the contact is in the system Blocked group.
+     */
+    isBlocked(contactId: string): boolean;
+    addToFavorites(contactId: string): MajikContactGroup;
+    removeFromFavorites(contactId: string): MajikContactGroup;
+    /**
+     * Adds the contact to the Blocked group and calls contact.block() on the directory.
+     */
+    blockContact(contactId: string): MajikContactGroup;
+    /**
+     * Removes the contact from the Blocked group.
+     * Calls contact.unblock() only if the contact is not re-blocked by any other mechanism.
+     */
+    unblockContact(contactId: string): MajikContactGroup;
+    getFavoritesGroup(): MajikContactGroup;
+    getBlockedGroup(): MajikContactGroup;
+    /**
+     * Must be called whenever a contact is removed from MajikContactDirectory.
+     * Auto-removes the contact from every group it belongs to and cleans up the reverse index.
+     *
+     * Usage:
+     *   const response = directory.removeContact(id);
+     *   if (response.success) manager.handleContactRemoved(id);
+     */
+    handleContactRemoved(contactId: string): void;
+    toJSON(): MajikContactGroupManagerData;
+    /**
+     * Restores all groups from serialized data.
+     * Clears existing user groups but preserves system groups (they are re-bootstrapped).
+     * Rebuilds the reverse index from scratch.
+     */
+    fromJSON(data: MajikContactGroupManagerData): this;
+    private indexAdd;
+    private indexRemove;
+    /**
+     * Unblocks a contact on the directory only if the contact is no longer
+     * a member of the system Blocked group. Guards against a race where
+     * the contact was re-added before unblock is processed.
+     */
+    private syncUnblock;
+    private assertDirectory;
+    private assertGroupId;
+    private assertContactId;
+    private assertContactIdArray;
+    private assertGroupInstance;
+    private assertNotSystemId;
+    /**
+     * Resolves a contact from the directory and throws a descriptive error if not found.
+     */
+    private getContactOrThrow;
+    /**
+     * Validates that all provided contact IDs exist in the directory.
+     * Collects all missing IDs and throws once with the full list,
+     * rather than failing on the first missing contact.
+     */
+    private assertContactsExist;
+}