@majikah/majik-message 0.2.20 → 0.3.0

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

@@ -0,0 +1,27 @@
+import { MajikContactDirectoryData, MajikContactManagerJSON } from "./types";
+export interface MajikMessageRawJSON extends Record<string, unknown> {
+    id: string;
+    contacts: MajikContactManagerJSON | MajikContactDirectoryData;
+    envelopeCache: unknown;
+    ownAccounts?: unknown;
+}
+/**
+ * Accepts a raw parsed JSON object from IDB/storage and guarantees the
+ * returned value always uses the current `MajikContactManagerJSON` shape
+ * for its `contacts` field — even if the blob was saved before groups existed.
+ *
+ * This is the single migration choke-point.  Call it once at the top of
+ * `MajikMessage.fromJSON()` before touching any field.
+ *
+ * Migration performed (legacy → current):
+ *   contacts: { contacts: [...] }
+ *   →
+ *   contacts: { contacts: [...], groups: { groups: [] } }
+ *
+ * The empty `groups` payload means `MajikContactGroupManager.fromJSON()`
+ * will bootstrap the two system groups (Favorites, Blocked) with no members,
+ * which is exactly correct for a first-time migration.
+ */
+export declare function migrateMajikMessageJSON(raw: unknown): MajikMessageRawJSON & {
+    contacts: MajikContactManagerJSON;
+};

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

@@ -0,0 +1,84 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// majik-contact-migration.ts
+//
+// Detects whether a persisted MajikMessage JSON blob was saved before
+// MajikContactManager existed (legacy) or after (current), and returns a
+// normalised MajikMessageJSON that always carries the new shape.
+//
+// Legacy shape (pre-migration):
+//   { id, contacts: { contacts: [...] }, envelopeCache, ownAccounts?, pinHash? }
+//   ↑ contacts is a MajikContactDirectoryData — no `groups` field
+//
+// Current shape (post-migration):
+//   { id, contacts: { contacts: [...], groups: { groups: [...] } }, envelopeCache, ... }
+//   ↑ contacts is a MajikContactManagerJSON — always has both `contacts` and `groups`
+// ─────────────────────────────────────────────────────────────────────────────
+/* -------------------------------
+ * Shape-detection helpers
+ * ------------------------------- */
+/**
+ * Returns true when the blob looks like a legacy save that only has
+ * a flat `{ contacts: [...] }` directory payload — no `groups` key.
+ */
+function isLegacyContactsShape(raw) {
+    if (!raw || typeof raw !== "object")
+        return false;
+    const obj = raw;
+    // Must have a `contacts` field that is an object …
+    if (!obj.contacts || typeof obj.contacts !== "object")
+        return false;
+    const contacts = obj.contacts;
+    // … that contains a `contacts` array (the raw serialized contacts) …
+    if (!Array.isArray(contacts.contacts))
+        return false;
+    // … but does NOT yet have a `groups` field — that is the migration trigger.
+    return !("groups" in contacts);
+}
+/**
+ * Accepts a raw parsed JSON object from IDB/storage and guarantees the
+ * returned value always uses the current `MajikContactManagerJSON` shape
+ * for its `contacts` field — even if the blob was saved before groups existed.
+ *
+ * This is the single migration choke-point.  Call it once at the top of
+ * `MajikMessage.fromJSON()` before touching any field.
+ *
+ * Migration performed (legacy → current):
+ *   contacts: { contacts: [...] }
+ *   →
+ *   contacts: { contacts: [...], groups: { groups: [] } }
+ *
+ * The empty `groups` payload means `MajikContactGroupManager.fromJSON()`
+ * will bootstrap the two system groups (Favorites, Blocked) with no members,
+ * which is exactly correct for a first-time migration.
+ */
+export function migrateMajikMessageJSON(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new Error("migrateMajikMessageJSON: input must be a non-null object");
+    }
+    const obj = raw;
+    if (!obj.id || typeof obj.id !== "string") {
+        throw new Error("migrateMajikMessageJSON: missing required field 'id'");
+    }
+    // ── Already in current shape — pass through untouched ────────────────────
+    if (!isLegacyContactsShape(obj)) {
+        // Validate it at least has the expected structure
+        const contacts = obj.contacts;
+        if (!contacts || !Array.isArray(contacts.contacts) || !contacts.groups) {
+            throw new Error("migrateMajikMessageJSON: 'contacts' field has an unrecognised shape — " +
+                "expected either a legacy { contacts: [...] } or current { contacts: [...], groups: {...} }");
+        }
+        return obj;
+    }
+    // ── Legacy shape — lift it into the current shape ─────────────────────────
+    console.info("[MajikMessage] Migrating persisted state from legacy contacts schema → " +
+        "MajikContactManager schema. Groups will be initialised empty.");
+    const legacyContacts = obj.contacts;
+    const migratedContacts = {
+        contacts: legacyContacts, // preserve all serialized contacts as-is
+        groups: { groups: [] }, // empty groups — system groups are bootstrapped at runtime
+    };
+    return {
+        ...obj,
+        contacts: migratedContacts,
+    };
+}

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

@@ -0,0 +1,11 @@
+import { SerializedMajikContact, SerializedMajikContactGroup } from "@majikah/majik-contact";
+export interface MajikContactManagerJSON {
+    contacts: MajikContactDirectoryData;
+    groups: MajikContactGroupManagerData;
+}
+export interface MajikContactDirectoryData {
+    contacts: SerializedMajikContact[];
+}
+export interface MajikContactGroupManagerData {
+    groups: SerializedMajikContactGroup[];
+}

package/dist/core/contacts/types.js

@@ -0,0 +1,4 @@
+/* -------------------------------
+ * Types
+ * ------------------------------- */
+export {};

package/dist/majik-message.d.ts

@@ -1,27 +1,33 @@
-import { MajikContact, type MajikContactMeta, type SerializedMajikContact } from "@majikah/majik-contact";
+import { MajikContact, MajikContactGroup, MajikContactGroupMeta, type MajikContactMeta, type SerializedMajikContact } from "@majikah/majik-contact";
 import { MessageEnvelope } from "./core/messages/message-envelope";
 import { EnvelopeCache, type EnvelopeCacheItem, type EnvelopeCacheJSON } from "./core/messages/envelope-cache";
 import { MajikKeyStore } from "./core/crypto/keystore";
-import { MajikContactDirectory, type MajikContactDirectoryData } from "./core/contacts/majik-contact-directory";
 import type { DecryptFileOptions, EncryptFileOptions, EncryptFileResult, MAJIK_API_RESPONSE, MajikMessagePublicKey } from "./core/types";
 import { MajikMessageChat } from "./core/database/chat/majik-message-chat";
 import { MajikMessageIdentity } from "./core/database/system/identity";
 import { MajikKey } from "@majikah/majik-key";
 import { MajikFile, MajikFileJSON } from "@majikah/majik-file";
 import { EnvelopeInfo, ExpectedSigner, MajikSignature, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignatoryInfo, type MajikSignatureJSON, type MajikSignerPublicKeys, type VerificationResult } from "@majikah/majik-signature";
-type MajikMessageEvents = "message" | "envelope" | "untrusted" | "error" | "new-account" | "new-contact" | "removed-account" | "removed-contact" | "active-account-change";
+import { MajikContactManager } from "./core/contacts/majik-contact-manager";
+import { MajikContactManagerJSON } from "./core/contacts/types";
+type MajikMessageEvents = "message" | "envelope" | "untrusted" | "error" | "new-account" | "new-contact" | "new-contact-group" | "removed-account" | "removed-contact" | "removed-contact-group" | "contact-group-change" | "active-account-change";
 interface MajikMessageStatic<T extends MajikMessage> {
     new (config: MajikMessageConfig, id?: string): T;
     fromJSON(json: MajikMessageJSON): Promise<T>;
 }
 export interface MajikMessageConfig {
     keyStore?: typeof MajikKeyStore;
-    contactDirectory?: MajikContactDirectory;
+    /**
+     * Optional pre-constructed MajikContactManager.
+     * When omitted, MajikMessage creates a fresh one internally.
+     * Pass one when restoring state from fromJSON() or loadState().
+     */
+    contactManager?: MajikContactManager;
     envelopeCache?: EnvelopeCache;
 }
 export interface MajikMessageJSON {
     id: string;
-    contacts: MajikContactDirectoryData;
+    contacts: MajikContactManagerJSON;
     envelopeCache: EnvelopeCacheJSON;
     ownAccounts?: {
         accounts: SerializedMajikContact[];
@@ -31,11 +37,9 @@ export interface MajikMessageJSON {
 type EventCallback = (...args: any[]) => void;
 export declare class MajikMessage {
     private userProfile;
-    private pinHash?;
     private id;
-    private contactDirectory;
+    private contacts;
     private envelopeCache;
-    private scanner;
     private listeners;
     private ownAccounts;
     private ownAccountsOrder;
@@ -104,9 +108,10 @@ export declare class MajikMessage {
     updatePassphrase(currentPassphrase: string, newPassphrase: string, id?: string): Promise<void>;
     getContactByID(id: string): MajikContact | null;
     hasContact(id: string): boolean;
-    getContactByPublicKey(publicKeyBase64: string): Promise<MajikContact | null>;
-    exportContactAsJSON(contactId: string): Promise<string | null>;
-    exportContactAsString(contactId: string): Promise<string | null>;
+    hasContactByPublicKeyBase64(publicKey: MajikMessagePublicKey): Promise<boolean>;
+    getContactByPublicKey(publicKeyBase64: MajikMessagePublicKey): Promise<MajikContact | null>;
+    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>;
@@ -120,6 +125,134 @@ export declare class MajikMessage {
     isContactMajikahRegistered(id: string): boolean;
     isContactMajikahIdentityChecked(id: string): boolean;
     setContactMajikahStatus(id: string, status: boolean): void;
+    /**
+     * Creates and registers a new user-defined group.
+     * Throws if a group with the same ID already exists.
+     */
+    createGroup(id: string, name: string, meta?: Partial<Omit<MajikContactGroupMeta, "name">>, initialMemberIds?: string[]): this;
+    /**
+     * Registers an already-constructed MajikContactGroup instance.
+     * Throws if a group with the same ID already exists.
+     */
+    addGroup(group: MajikContactGroup): this;
+    /**
+     * Removes a user group by ID.
+     * System groups (Favorites, Blocked) cannot be deleted.
+     */
+    removeGroup(id: string): MAJIK_API_RESPONSE;
+    /**
+     * Returns a group by ID, or undefined if not found.
+     */
+    getContactGroup(id: string): MajikContactGroup | undefined;
+    /**
+     * Returns a group by ID. Throws if not found.
+     */
+    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.
+     */
+    listContactGroups(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">>): this;
+    /**
+     * 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): this;
+    /**
+     * Adds multiple contacts to a group in one call (all-or-nothing).
+     */
+    addContactsToGroup(groupID: string, contactIds: string[]): this;
+    /**
+     * 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): this;
+    /**
+     * 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): this;
+    /**
+     * Returns all hydrated MajikContact instances in the given group.
+     * Contacts removed from the directory since last save are silently skipped.
+     */
+    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).
+     */
+    addContactToFavorites(contactID: string): this;
+    /**
+     * Removes the contact from the Favorites group (idempotent).
+     */
+    removeContactFromFavorites(contactID: string): this;
+    /**
+     * Returns true if the contact is in the Favorites group.
+     */
+    isContactFavorite(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).
+     */
+    clearDirectory(): this;
     /**
      * Compose and encrypt a message for one or more recipients.
      * Single recipient → solo envelope. Two or more → group envelope.
@@ -208,7 +341,7 @@ export declare class MajikMessage {
      *   metadata: row,
      * });
      * if (signature) {
-     *   const result = await majik.verifyMajikFile(file, { contactId: row.user_id });
+     *   const result = await majik.verifyMajikFile(file, { contactID: row.user_id });
      * }
      * ```
      */
@@ -248,7 +381,7 @@ export declare class MajikMessage {
      * if the instance was restored from a metadata-only Supabase row.
      *
      * Signer resolution:
-     *   - contactId: looked up in the contact directory (own accounts included)
+     *   - contactID: looked up in the contact directory (own accounts included)
      *   - publicKeyBase64: looked up via contact directory
      *   - key: used directly (skips directory lookup)
      *   - none provided: falls back to public keys embedded in the signature
@@ -259,12 +392,12 @@ export declare class MajikMessage {
      * @example — verify against the file's owner contact
      *   file.attachBinary(await r2.get(row.r2_key).arrayBuffer());
      *   const result = await majik.verifyMajikFile(file, {
-     *     contactId: ownerContactId,
+     *     contactID: ownerContactId,
      *   });
      *   if (result?.valid) console.log("Verified, signed by", result.signerId);
      */
     verifyMajikFile(file: MajikFile, options?: {
-        contactId?: string;
+        contactID?: string;
         publicKeyBase64?: string;
         key?: MajikKey;
     }): Promise<VerificationResult | null>;
@@ -284,12 +417,12 @@ export declare class MajikMessage {
      *
      * @example
      *   const result = await majik.verifyMajikFileBinary(file, {
-     *     contactId: "contact_abc",
+     *     contactID: "contact_abc",
      *   });
      *   if (result.valid) console.log("Plaintext verified");
      */
     verifyMajikFileBinary(file: MajikFile, options?: {
-        contactId?: string;
+        contactID?: string;
         publicKeyBase64?: string;
         key?: MajikKey;
         decryptAccountId?: string;
@@ -454,12 +587,12 @@ export declare class MajikMessage {
      *
      * @example
      *   const result = await majik.verifyText("Hello world", sig, {
-     *     contactId: "contact_abc",
+     *     contactID: "contact_abc",
      *   });
      *   if (result.valid) console.log("Authentic");
      */
     verifyText(text: string, signature: MajikSignature | MajikSignatureJSON | string, options?: {
-        contactId?: string;
+        contactID?: string;
         publicKeyBase64?: string;
         key?: MajikKey;
         expectedSignerId?: string;
@@ -478,12 +611,12 @@ export declare class MajikMessage {
      * @example
      *   const row = await db.findOne({ doc_id });
      *   const result = await majik.verifyDetached(docBytes, row.signature, {
-     *     contactId: row.signer_contact_id,
+     *     contactID: row.signer_contact_id,
      *   });
      *   if (result.valid) console.log("Signed by", result.signerId);
      */
     verifyDetached(content: Uint8Array | string, serializedSignature: string, options?: {
-        contactId?: string;
+        contactID?: string;
         publicKeyBase64?: string;
         key?: MajikKey;
         expectedSignerId?: string;
@@ -554,9 +687,6 @@ export declare class MajikMessage {
         raw: Uint8Array;
     }>;
     isPassphraseValid(passphrase: string, id?: string): Promise<boolean>;
-    scanDOM(rootNode: Node): void;
-    startDOMObserver(rootNode: Node): void;
-    stopDOMObserver(): void;
     on(event: MajikMessageEvents, callback: EventCallback): void;
     off(event: MajikMessageEvents, callback?: EventCallback): void;
     private emit;
@@ -655,7 +785,7 @@ export declare class MajikMessage {
      * > against a known contact fingerprint before trusting the result.
      *
      * @example — verify against a known contact
-     *   const result = await majik.verifyContent(docBytes, sig, { contactId: "contact_abc" });
+     *   const result = await majik.verifyContent(docBytes, sig, { contactID: "contact_abc" });
      *   if (result.valid) console.log("Authentic, signed by:", result.signerId);
      *
      * @example — verify using embedded keys (self-reported)
@@ -663,7 +793,7 @@ export declare class MajikMessage {
      *   // always check result.signerId matches a known fingerprint
      */
     verifyContent(content: Uint8Array | string, signature: MajikSignature | MajikSignatureJSON, options?: {
-        contactId?: string;
+        contactID?: string;
         publicKeyBase64?: string;
         key?: MajikKey;
         expectedSignerId?: string;
@@ -680,16 +810,16 @@ export declare class MajikMessage {
      * envelope are used (self-reported — see security note on verifyContent).
      *
      * @example — verify a signed PDF against a known contact
-     *   const result = await majik.verifyFile(signedPdf, { contactId: "contact_abc" });
+     *   const result = await majik.verifyFile(signedPdf, { contactID: "contact_abc" });
      *   if (result.valid) console.log("Verified:", result.signerId, result.timestamp);
      *
      * @example — check own signed file using active account
      *   const result = await majik.verifyFile(signedWav, {
-     *     contactId: majik.getActiveAccount()?.id,
+     *     contactID: majik.getActiveAccount()?.id,
      *   });
      */
     verifyFile(file: Blob, options?: {
-        contactId?: string;
+        contactID?: string;
         publicKeyBase64?: string;
         key?: MajikKey;
         expectedSignerId?: string;
@@ -708,7 +838,7 @@ export declare class MajikMessage {
      * @example
      *   const results = await majik.batchVerifyFiles(
      *     [pdfBlob, wavBlob, mp4Blob],
-     *     { contactId: "contact_abc" },
+     *     { contactID: "contact_abc" },
      *   );
      *   const allValid = results.every(r => r.valid);
      */
@@ -717,7 +847,7 @@ export declare class MajikMessage {
         mimeType?: string;
         expectedSignerId?: string;
     }>, options?: {
-        contactId?: string;
+        contactID?: string;
         publicKeyBase64?: string;
         key?: MajikKey;
         expectedSignerId?: string;
@@ -757,7 +887,7 @@ export declare class MajikMessage {
      *
      * @example
      *   if (await majik.isFileSigned(file)) {
-     *     const result = await majik.verifyFile(file, { contactId });
+     *     const result = await majik.verifyFile(file, { contactID });
      *   }
      */
     isFileSigned(file: Blob, options?: {
@@ -994,11 +1124,6 @@ export declare class MajikMessage {
      * throughout MajikMessage — consistent account/contact resolution in one place.
      */
     private _resolveSignerPublicKeys;
-    setPIN(pin: string): Promise<void>;
-    clearPIN(): Promise<void>;
-    isValidPIN(pin: string): Promise<boolean>;
-    getPinHash(): string | null;
-    private static _hashPIN;
     toJSON(): Promise<MajikMessageJSON>;
     static fromJSON<T extends MajikMessage>(this: new (config: MajikMessageConfig, id?: string) => T, json: MajikMessageJSON): Promise<T>;
     private attachAutosaveHandlers;