@majikah/majik-message 0.3.5 → 0.3.7

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

@@ -2,235 +2,143 @@ import { MajikContact, MajikContactData, MajikContactGroup, MajikContactGroupMet
 import { MajikContactDirectory } from "./majik-contact-directory";
 import { MajikContactGroupManager } from "./majik-contact-groups";
 import { MAJIK_API_RESPONSE } from "../types";
-import { MessageEnvelope } from "../messages/message-envelope";
 import { MajikContactManagerJSON } from "./types";
-/**
- * Unified facade over MajikContactDirectory and MajikContactGroupManager.
- *
- * Responsibilities:
- *  - Owns both the directory and the group manager as a single cohesive unit
- *  - Proxies all directory methods so MajikMessage call sites need only change
- *    `contactDirectory` → `contacts` with no logic changes
- *  - Wires lifecycle hooks automatically so callers can never forget them:
- *      • removeContact()  → always calls groups.handleContactRemoved()
- *      • blockContact()   → always syncs the Blocked system group
- *      • unblockContact() → always syncs the Blocked system group
- *  - Exposes the group manager via `.group` for all group-specific operations
- *  - Serializes both directory and groups into one unified payload for
- *    MajikMessage.toJSON() / MajikMessage.fromJSON()
- *
- * Construction:
- *  - Pass nothing → fresh directory + fresh group manager (new session)
- *  - Pass a directory → wraps it, creates a fresh group manager bound to it
- *  - Pass both → fully restores a prior session (used by fromJSON)
- */
+import { MajikContactStorageAdapter } from "../storage/contact-directory/contacts/_types";
+import { MajikContactGroupStorageAdapter } from "../storage/contact-directory/groups/_types";
+export interface MajikContactManagerAdapters {
+    contacts?: MajikContactStorageAdapter;
+    groups?: MajikContactGroupStorageAdapter;
+}
 export declare class MajikContactManager {
     private readonly directory;
     private readonly groupManager;
-    constructor(directory?: MajikContactDirectory, groupManager?: MajikContactGroupManager);
+    private _contactAdapter;
+    private _groupAdapter;
+    constructor(directory?: MajikContactDirectory, groupManager?: MajikContactGroupManager, adapters?: MajikContactManagerAdapters);
+    get contactAdapter(): MajikContactStorageAdapter;
+    get groupAdapter(): MajikContactGroupStorageAdapter;
     /**
-     * Direct access to the full MajikContactGroupManager API.
-     * Use for all group-specific operations:
-     *   manager.group.addToFavorites(contactId)
-     *   manager.group.createGroup(id, name)
-     *   manager.group.getContactsInGroup(groupId)
-     *   etc.
+     * Swap both adapters at runtime. Does NOT migrate data.
+     *
+     * Migration pattern:
+     * ```ts
+     * const snap = await manager.toJSON();
+     * manager.setAdapters({ contacts: new IDBContactAdapter(), groups: new IDBGroupAdapter() });
+     * await manager.hydrate();                    // warms from new (empty) adapters
+     * await manager.bulkRestoreFromJSON(snap);    // writes old data into new adapters
+     * ```
+     */
+    setAdapters(adapters: MajikContactManagerAdapters): void;
+    /**
+     * Load all contacts and groups from the adapters into the in-memory
+     * directory and group manager. Call once after construction (or after
+     * swapping adapters).
+     *
+     * Restoration order:
+     *  1. Contacts — must come first so groups can validate member existence.
+     *  2. Groups — restored via groupManager.fromJSON() which rebuilds the
+     *     reverse index and re-bootstraps system groups.
+     *  3. Orphan pruning — any group member ID not present in the restored
+     *     directory is silently removed (guards against data drift).
      */
-    get group(): MajikContactGroupManager;
+    hydrate(): Promise<void>;
     /**
-     * Direct access to the underlying MajikContactDirectory.
-     * Prefer the proxied methods on this class over accessing the directory
-     * directly — they keep group state in sync automatically.
+     * Persists a single contact to the adapter (called after every mutating
+     * operation that affects a contact's serialized form).
      */
-    get directory_(): MajikContactDirectory;
-    addContact(contact: MajikContact): this;
-    addContacts(contacts: MajikContact[]): this;
+    private persistContact;
     /**
-     * Removes a contact from the directory and automatically removes them
-     * from every group they belong to via the group manager hook.
-     * The two operations are always atomic from the caller's perspective.
+     * Persists a single group to the adapter.
      */
-    removeContact(id: string): MAJIK_API_RESPONSE;
-    getContact(id: string): MajikContact | undefined;
-    getContactByFingerprint(fingerprint: string): MajikContact | undefined;
-    getContactByPublicKeyBase64(publicKeyBase64: string): Promise<MajikContact | undefined>;
-    hasContact(id: string): boolean;
-    hasFingerprint(fingerprint: string): boolean;
-    hasContactByPublicKeyBase64(publicKeyBase64: string): Promise<boolean>;
-    listContacts(sortedByLabel?: boolean, majikahOnly?: boolean): MajikContact[];
-    updateContactMeta(id: string, meta: Partial<MajikContactData["meta"]>): MajikContact;
+    private persistGroup;
     /**
-     * Blocks a contact on the directory AND adds them to the system Blocked
-     * group — both sides are always kept in sync.
+     * Adds a contact to the directory and persists it to the adapter.
      */
-    blockContact(id: string): MajikContact;
+    addContact(contact: MajikContact): Promise<this>;
     /**
-     * Unblocks a contact on the directory AND removes them from the system
-     * Blocked group — both sides are always kept in sync.
+     * Adds multiple contacts atomically — adapter write uses bulkSave.
      */
-    unblockContact(id: string): MajikContact;
-    setMajikahStatus(id: string, status: boolean): MajikContact;
-    isMajikahRegistered(id: string): boolean;
-    isMajikahIdentityChecked(id: string): boolean;
-    hasContactForEnvelope(envelope: MessageEnvelope): boolean;
+    addContacts(contacts: MajikContact[]): Promise<this>;
     /**
-     * Creates and registers a new user-defined group.
-     * Throws if a group with the same ID already exists.
+     * Removes a contact from the directory, all groups, and the adapter.
      */
-    createGroup(id: string, name: string, meta?: Partial<Omit<MajikContactGroupMeta, "name">>, initialMemberIds?: string[]): MajikContactGroup;
+    removeContact(id: string): Promise<MAJIK_API_RESPONSE>;
     /**
-     * Registers an already-constructed MajikContactGroup instance.
-     * Throws if a group with the same ID already exists.
+     * Updates contact metadata and persists the change.
      */
-    addGroup(group: MajikContactGroup): this;
+    updateContactMeta(id: string, meta: Partial<MajikContactData["meta"]>): Promise<MajikContact>;
     /**
-     * Removes a user group by ID.
-     * System groups (Favorites, Blocked) cannot be deleted.
+     * Blocks a contact and persists both the contact and the Blocked group.
      */
-    removeGroup(id: string): MAJIK_API_RESPONSE;
+    blockContact(id: string): Promise<MajikContact>;
     /**
-     * Returns a group by ID, or undefined if not found.
+     * Unblocks a contact and persists both the contact and the Blocked group.
      */
-    getGroup(id: string): MajikContactGroup | undefined;
+    unblockContact(id: string): Promise<MajikContact>;
+    setMajikahStatus(id: string, status: boolean): Promise<MajikContact>;
     /**
-     * Returns a group by ID. Throws if not found.
+     * Clears all contacts and groups from both the in-memory stores and adapters.
      */
+    clear(): Promise<this>;
+    getContact(id: string): MajikContact | undefined;
+    getContactByFingerprint(fingerprint: string): MajikContact | undefined;
+    getContactByPublicKeyBase64(publicKeyBase64: string): Promise<MajikContact | undefined>;
+    hasContact(id: string): boolean;
+    hasFingerprint(fingerprint: string): boolean;
+    hasContactByPublicKeyBase64(publicKeyBase64: string): Promise<boolean>;
+    listContacts(sortedByLabel?: boolean, majikahOnly?: boolean): MajikContact[];
+    isMajikahRegistered(id: string): boolean;
+    isMajikahIdentityChecked(id: string): boolean;
+    get group(): MajikContactGroupManager;
+    get directory_(): MajikContactDirectory;
+    createGroup(id: string, name: string, meta?: Partial<Omit<MajikContactGroupMeta, "name">>, initialMemberIds?: string[]): Promise<MajikContactGroup>;
+    addGroup(group: MajikContactGroup): Promise<this>;
+    removeGroup(id: string): Promise<MAJIK_API_RESPONSE>;
+    getGroup(id: string): MajikContactGroup | undefined;
     getGroupOrThrow(id: string): MajikContactGroup;
-    /**
-     * Returns true if a group with the given ID exists.
-     */
     hasGroup(id: string): boolean;
-    /**
-     * Returns all groups.
-     *
-     * @param includeSystem  Include system groups (Favorites, Blocked). Default: true.
-     * @param sortedByName   Sort results alphabetically by group name. Default: false.
-     */
     listGroups(includeSystem?: boolean, sortedByName?: boolean): MajikContactGroup[];
-    /**
-     * Returns only user-created groups (excludes Favorites and Blocked).
-     * Sorted alphabetically by name.
-     */
     listUserGroups(sortedByName?: boolean): MajikContactGroup[];
-    /**
-     * Returns only system groups (Favorites and Blocked).
-     */
     listSystemGroups(): MajikContactGroup[];
-    /**
-     * Updates mutable metadata on a group (name, description).
-     * Name is locked on system groups — will throw if attempted.
-     */
-    updateGroupMeta(id: string, meta: Partial<Pick<MajikContactGroupMeta, "name" | "description" | "color">>): MajikContactGroup;
-    /**
-     * Adds a contact to a group.
-     * Validates the contact exists in the directory.
-     * If the group is the system Blocked group, also calls contact.block().
-     * Throws if the contact is already a member — use addContactToGroupIfAbsent for idempotent.
-     */
-    addContactToGroup(groupId: string, contactId: string): MajikContactGroup;
-    /**
-     * Idempotent variant — does not throw if the contact is already a member.
-     */
-    addContactToGroupIfAbsent(groupId: string, contactId: string): MajikContactGroup;
-    /**
-     * Adds multiple contacts to a group in one call (all-or-nothing).
-     */
-    addContactsToGroup(groupId: string, contactIds: string[]): MajikContactGroup;
-    /**
-     * Removes a contact from a group.
-     * If the group is the system Blocked group, also calls contact.unblock().
-     * Throws if the contact is not a member — 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.
-     */
-    moveContactBetweenGroups(contactId: string, fromGroupId: string, toGroupId: string): void;
-    /**
-     * Returns all hydrated MajikContact instances in the given group.
-     * Contacts removed from the directory since last save are silently skipped.
-     */
+    updateGroupMeta(id: string, meta: Partial<Pick<MajikContactGroupMeta, "name" | "description" | "color">>): Promise<MajikContactGroup>;
+    addContactToGroup(groupId: string, contactId: string): Promise<MajikContactGroup>;
+    addContactToGroupIfAbsent(groupId: string, contactId: string): Promise<MajikContactGroup>;
+    addContactsToGroup(groupId: string, contactIds: string[]): Promise<MajikContactGroup>;
+    removeContactFromGroup(groupId: string, contactId: string): Promise<MajikContactGroup>;
+    removeContactFromGroupIfPresent(groupId: string, contactId: string): Promise<MajikContactGroup>;
+    moveContactBetweenGroups(contactId: string, fromGroupId: string, toGroupId: string): Promise<void>;
     getContactsInGroup(groupId: string): MajikContact[];
-    /**
-     * Returns hydrated contacts in the group, sorted by label (or ID if no label).
-     */
     getContactsInGroupSorted(groupId: string): MajikContact[];
-    /**
-     * Returns true if the contact is a member of the given group.
-     */
     isContactInGroup(groupId: string, contactId: string): boolean;
-    /**
-     * Returns all groups the contact belongs to.
-     */
     getGroupsForContact(contactId: string): MajikContactGroup[];
-    /**
-     * Returns all group IDs the contact belongs to.
-     */
     getGroupIdsForContact(contactId: string): string[];
-    /**
-     * Adds the contact to the Favorites group (idempotent).
-     */
-    addToFavorites(contactId: string): MajikContactGroup;
-    /**
-     * Removes the contact from the Favorites group (idempotent).
-     */
-    removeFromFavorites(contactId: string): MajikContactGroup;
-    /**
-     * Returns true if the contact is in the Favorites group.
-     */
+    addToFavorites(contactId: string): Promise<MajikContactGroup>;
+    removeFromFavorites(contactId: string): Promise<MajikContactGroup>;
     isFavorite(contactId: string): boolean;
-    /**
-     * Returns true if the contact is in the Blocked group.
-     */
     isContactBlocked(contactId: string): boolean;
-    /**
-     * Returns the Favorites system group instance.
-     */
     getFavoritesGroup(): MajikContactGroup;
-    /**
-     * Returns the Blocked system group instance.
-     */
     getBlockedGroup(): MajikContactGroup;
-    /**
-     * Returns all contacts in the Favorites group as hydrated MajikContact instances.
-     */
     getFavoriteContacts(): MajikContact[];
-    /**
-     * Returns all contacts in the Blocked group as hydrated MajikContact instances.
-     */
     getBlockedContacts(): MajikContact[];
-    /**
-     * Clears both the directory and all group memberships.
-     * System groups are preserved (re-bootstrapped by the group manager).
-     */
-    clear(): this;
-    /**
-     * Serializes both the directory and all groups into a single unified payload.
-     * This is what MajikMessage.toJSON() should persist.
-     */
+    exportContactAsJSON(contactId: string): Promise<string | null>;
+    exportContactAsString(contactId: string): Promise<string | null>;
+    importContactFromJSON(jsonStr: string): Promise<MAJIK_API_RESPONSE>;
+    importContactFromString(base64Str: string): Promise<MAJIK_API_RESPONSE>;
+    exportContactCompressed(contact: MajikContact): Promise<string>;
+    importContactCompressed(base64Str: string): Promise<MajikContact>;
     toJSON(): Promise<MajikContactManagerJSON>;
     /**
-     * Restores a MajikContactManager from a unified serialized payload.
-     *
-     * Restoration order:
-     *  1. Restore the directory (contacts + crypto keys)
-     *  2. Restore groups via the group manager
-     *  3. Silently strip any group member IDs that no longer exist in the
-     *     restored directory (orphan pruning) — guards against data drift
-     *     between directory and group state across serialization rounds
-     *
-     * @param data   The payload produced by toJSON().
+     * Restore from a JSON snapshot into the current adapters.
+     * Writes all contacts and groups through to the adapters.
+     * Used after setAdapters() to migrate data into a new store.
      */
-    static fromJSON(data: MajikContactManagerJSON): Promise<MajikContactManager>;
+    bulkRestoreFromJSON(data: MajikContactManagerJSON): Promise<void>;
+    static fromJSON(data: MajikContactManagerJSON, adapters?: MajikContactManagerAdapters): Promise<MajikContactManager>;
     /**
-     * Walks every group and removes any member ID not present in the directory.
-     * Operates directly on the group instances — no re-serialization needed.
+     * Persists every group currently in the group manager to the adapter.
+     * Used after bulk contact removal where multiple groups may be affected.
      */
+    private _persistAllGroups;
     private static pruneOrphanedMembers;
     private assertGroupManagerInstance;
 }