@majikah/majik-universal-id-client 0.0.12 → 0.0.14

package/dist/core/client-state-manager.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @file client-state-manager.ts
+ * @description ClientStateManager — typed read/write interface over a
+ * pluggable ClientStateStorageAdapter.
+ *
+ * Responsibilities:
+ *   - Async get / set / remove for each well-known client-state key
+ *   - In-memory cache in front of the adapter (warm via hydrate())
+ *   - Typed accessors for `accountOrder` and `invoiceDefaults` so callers
+ *     never touch raw JSON strings
+ *   - Generic `get` / `set` escape hatch for any future keys
+ *   - Adapter can be swapped at runtime via setAdapter()
+ *
+ * Usage:
+ * ```ts
+ * const stateManager = new ClientStateManager(new IDBClientStateAdapter());
+ * await stateManager.hydrate();
+ *
+ * await stateManager.setAccountOrder(["id1", "id2"]);
+ * const order = await stateManager.getAccountOrder(); // ["id1", "id2"]
+ * ```
+ *
+ * MajikBuwizClient owns this instance and calls hydrate() during its own
+ * hydrate() pass. Callers should never need to hydrate() again unless the
+ * adapter is swapped.
+ */
+import { AccountOrderValue, ClientStateEntry, ClientStateStorageAdapter } from "./storage/client-state/_types";
+export declare class ClientStateManager {
+    /** In-memory cache — warmed by hydrate(), kept in sync on every write. */
+    private _cache;
+    private _adapter;
+    /**
+     * @param adapter Defaults to InMemoryClientStateAdapter (non-persistent).
+     *   Pass IDBClientStateAdapter or SQLiteClientStateAdapter for persistence.
+     */
+    constructor(adapter?: ClientStateStorageAdapter);
+    get adapter(): ClientStateStorageAdapter;
+    /**
+     * Swap the storage adapter at runtime.
+     *
+     * Does NOT migrate data. To migrate:
+     * ```ts
+     * const entries = stateManager.listCachedEntries();
+     * stateManager.setAdapter(newAdapter);
+     * await stateManager.hydrate();
+     * await stateManager.bulkSet(entries);
+     * ```
+     */
+    setAdapter(adapter: ClientStateStorageAdapter): void;
+    /**
+     * Load all entries from the adapter into the in-memory cache.
+     * Call once after construction (MajikBuwizClient.hydrate() does this).
+     */
+    hydrate(): Promise<void>;
+    /**
+     * Retrieve a raw JSON string for any key. Returns `null` if not found.
+     * Prefer the typed accessors (getAccountOrder, getInvoiceDefaults) over this.
+     */
+    get(id: string): Promise<string | null>;
+    /**
+     * Persist a raw JSON string for any key.
+     * Prefer the typed accessors over this.
+     */
+    set(id: string, value: string): Promise<void>;
+    /**
+     * Remove a single key.
+     */
+    remove(id: string): Promise<boolean>;
+    /**
+     * Remove all stored state.
+     */
+    clear(): Promise<void>;
+    /**
+     * Whether a key exists in the cache.
+     * Accurate after hydrate(); use exists() for an authoritative adapter check.
+     */
+    hasCached(id: string): boolean;
+    /**
+     * Authoritative existence check against the adapter.
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * Snapshot of all cached entries — useful for adapter migration.
+     */
+    listCachedEntries(): ClientStateEntry[];
+    /**
+     * Persist multiple entries in one adapter call.
+     */
+    bulkSet(entries: ClientStateEntry[]): Promise<void>;
+    /**
+     * Retrieve the ordered list of own account IDs.
+     * Returns `null` if no order has been persisted yet.
+     */
+    getAccountOrder(): Promise<AccountOrderValue | null>;
+    /**
+     * Persist the ordered list of own account IDs.
+     */
+    setAccountOrder(order: AccountOrderValue): Promise<void>;
+    /**
+     * Remove the persisted account order (resets to insertion order on next
+     * hydrate).
+     */
+    removeAccountOrder(): Promise<void>;
+    count(): Promise<number>;
+}

package/dist/core/client-state-manager.js

@@ -0,0 +1,250 @@
+/**
+ * @file client-state-manager.ts
+ * @description ClientStateManager — typed read/write interface over a
+ * pluggable ClientStateStorageAdapter.
+ *
+ * Responsibilities:
+ *   - Async get / set / remove for each well-known client-state key
+ *   - In-memory cache in front of the adapter (warm via hydrate())
+ *   - Typed accessors for `accountOrder` and `invoiceDefaults` so callers
+ *     never touch raw JSON strings
+ *   - Generic `get` / `set` escape hatch for any future keys
+ *   - Adapter can be swapped at runtime via setAdapter()
+ *
+ * Usage:
+ * ```ts
+ * const stateManager = new ClientStateManager(new IDBClientStateAdapter());
+ * await stateManager.hydrate();
+ *
+ * await stateManager.setAccountOrder(["id1", "id2"]);
+ * const order = await stateManager.getAccountOrder(); // ["id1", "id2"]
+ * ```
+ *
+ * MajikBuwizClient owns this instance and calls hydrate() during its own
+ * hydrate() pass. Callers should never need to hydrate() again unless the
+ * adapter is swapped.
+ */
+import { CLIENT_STATE_KEYS, } from "./storage/client-state/_types";
+import { InMemoryClientStateAdapter } from "./storage/client-state/adapter-memory";
+// ---------------------------------------------------------------------------
+// ClientStateManager
+// ---------------------------------------------------------------------------
+export class ClientStateManager {
+    /** In-memory cache — warmed by hydrate(), kept in sync on every write. */
+    _cache = new Map();
+    _adapter;
+    /**
+     * @param adapter Defaults to InMemoryClientStateAdapter (non-persistent).
+     *   Pass IDBClientStateAdapter or SQLiteClientStateAdapter for persistence.
+     */
+    constructor(adapter = new InMemoryClientStateAdapter()) {
+        this._adapter = adapter;
+    }
+    // ── Adapter management ────────────────────────────────────────────────────
+    get adapter() {
+        return this._adapter;
+    }
+    /**
+     * Swap the storage adapter at runtime.
+     *
+     * Does NOT migrate data. To migrate:
+     * ```ts
+     * const entries = stateManager.listCachedEntries();
+     * stateManager.setAdapter(newAdapter);
+     * await stateManager.hydrate();
+     * await stateManager.bulkSet(entries);
+     * ```
+     */
+    setAdapter(adapter) {
+        this._adapter = adapter;
+    }
+    // ── Hydration ─────────────────────────────────────────────────────────────
+    /**
+     * Load all entries from the adapter into the in-memory cache.
+     * Call once after construction (MajikBuwizClient.hydrate() does this).
+     */
+    async hydrate() {
+        const entries = await this._adapter.list();
+        this._cache.clear();
+        for (const entry of entries) {
+            this._cache.set(entry.id, entry.value);
+        }
+    }
+    // ── Generic typed get / set / remove ─────────────────────────────────────
+    /**
+     * Retrieve a raw JSON string for any key. Returns `null` if not found.
+     * Prefer the typed accessors (getAccountOrder, getInvoiceDefaults) over this.
+     */
+    async get(id) {
+        const cached = this._cache.get(id);
+        if (cached !== undefined)
+            return cached;
+        // Cache miss — should not happen after hydrate() but defensive
+        const entry = await this._adapter.getById(id);
+        if (!entry)
+            return null;
+        this._cache.set(id, entry.value);
+        return entry.value;
+    }
+    /**
+     * Persist a raw JSON string for any key.
+     * Prefer the typed accessors over this.
+     */
+    async set(id, value) {
+        const entry = { id, value };
+        await this._adapter.save(entry);
+        this._cache.set(id, value);
+    }
+    /**
+     * Remove a single key.
+     */
+    async remove(id) {
+        const removed = await this._adapter.remove(id);
+        this._cache.delete(id);
+        return removed;
+    }
+    /**
+     * Remove all stored state.
+     */
+    async clear() {
+        await this._adapter.clear();
+        this._cache.clear();
+    }
+    /**
+     * Whether a key exists in the cache.
+     * Accurate after hydrate(); use exists() for an authoritative adapter check.
+     */
+    hasCached(id) {
+        return this._cache.has(id);
+    }
+    /**
+     * Authoritative existence check against the adapter.
+     */
+    async exists(id) {
+        if (this._cache.has(id))
+            return true;
+        return this._adapter.exists(id);
+    }
+    /**
+     * Snapshot of all cached entries — useful for adapter migration.
+     */
+    listCachedEntries() {
+        return Array.from(this._cache.entries()).map(([id, value]) => ({
+            id,
+            value,
+        }));
+    }
+    /**
+     * Persist multiple entries in one adapter call.
+     */
+    async bulkSet(entries) {
+        if (entries.length === 0)
+            return;
+        await this._adapter.bulkSave(entries);
+        for (const e of entries)
+            this._cache.set(e.id, e.value);
+    }
+    // ── Typed: account order ──────────────────────────────────────────────────
+    /**
+     * Retrieve the ordered list of own account IDs.
+     * Returns `null` if no order has been persisted yet.
+     */
+    async getAccountOrder() {
+        const raw = await this.get(CLIENT_STATE_KEYS.ACCOUNT_ORDER);
+        if (raw === null)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            console.warn("ClientStateManager: malformed account order — discarding.");
+            return null;
+        }
+    }
+    /**
+     * Persist the ordered list of own account IDs.
+     */
+    async setAccountOrder(order) {
+        await this.set(CLIENT_STATE_KEYS.ACCOUNT_ORDER, JSON.stringify(order));
+    }
+    /**
+     * Remove the persisted account order (resets to insertion order on next
+     * hydrate).
+     */
+    async removeAccountOrder() {
+        await this.remove(CLIENT_STATE_KEYS.ACCOUNT_ORDER);
+    }
+    // ── Typed: invoice defaults ───────────────────────────────────────────────
+    // /**
+    //  * Retrieve user-configured invoice defaults.
+    //  * Returns `null` if none have been saved yet.
+    //  */
+    // async getInvoiceDefaults(): Promise<InvoiceDefaults | null> {
+    //   const raw = await this.get(CLIENT_STATE_KEYS.INVOICE_DEFAULTS);
+    //   if (raw === null) return null;
+    //   try {
+    //     return JSON.parse(raw) as InvoiceDefaults;
+    //   } catch {
+    //     console.warn(
+    //       "ClientStateManager: malformed invoice defaults — discarding.",
+    //     );
+    //     return null;
+    //   }
+    // }
+    // /**
+    //  * Persist user-configured invoice defaults.
+    //  */
+    // async setInvoiceDefaults(defaults: InvoiceDefaults): Promise<void> {
+    //   await this.set(
+    //     CLIENT_STATE_KEYS.INVOICE_DEFAULTS,
+    //     JSON.stringify(defaults),
+    //   );
+    // }
+    // /**
+    //  * Remove the persisted invoice defaults.
+    //  */
+    // async removeInvoiceDefaults(): Promise<void> {
+    //   await this.remove(CLIENT_STATE_KEYS.INVOICE_DEFAULTS);
+    // }
+    // async currentInvoiceNumber(): Promise<number> {
+    //   const current = await this.getInvoiceDefaults();
+    //   const counter = current?.invoiceNumberCounter ?? 0;
+    //   return counter;
+    // }
+    // async incrementInvoiceNumber(): Promise<number> {
+    //   // 1. Get current defaults
+    //   const current = await this.getInvoiceDefaults();
+    //   // 2. Initialize safely if missing
+    //   const counter = current?.invoiceNumberCounter ?? 0;
+    //   const updated: InvoiceDefaults = {
+    //     ...(current ?? {
+    //       currency: "PHP" as any, // fallback — adjust if you have a real default
+    //     }),
+    //     invoiceNumberCounter: counter + 1,
+    //   };
+    //   // 3. Persist
+    //   await this.setInvoiceDefaults(updated);
+    //   // 4. Return the new value (useful for generating invoice number)
+    //   return updated.invoiceNumberCounter!;
+    // }
+    // async decrementInvoiceNumber(): Promise<number> {
+    //   // 1. Get current defaults
+    //   const current = await this.getInvoiceDefaults();
+    //   // 2. Initialize safely if missing
+    //   const counter = current?.invoiceNumberCounter ?? 0;
+    //   const updated: InvoiceDefaults = {
+    //     ...(current ?? {
+    //       currency: "PHP" as any, // fallback — adjust if you have a real default
+    //     }),
+    //     invoiceNumberCounter: counter - 1,
+    //   };
+    //   // 3. Persist
+    //   await this.setInvoiceDefaults(updated);
+    //   // 4. Return the new value (useful for generating invoice number)
+    //   return updated.invoiceNumberCounter!;
+    // }
+    // ── Async count ───────────────────────────────────────────────────────────
+    async count() {
+        return this._adapter.count();
+    }
+}

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,12 +1,6 @@
 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;
@@ -27,6 +21,10 @@ export declare class MajikContactDirectory {
     blockContact(id: string): MajikContact;
     unblockContact(id: string): MajikContact;
     hasContact(id: string): boolean;
+    /**
+     * Checks if a contact exists by their public key (base64)
+     */
+    hasContactByPublicKeyBase64(publicKeyBase64: string): Promise<boolean>;
     clear(): this;
     setMajikahStatus(id: string, status: boolean): MajikContact;
     isMajikahIdentityChecked(id: string): boolean;

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
  * ------------------------------- */
@@ -27,6 +17,12 @@ export class MajikContactDirectory {
      * Contact Management
      * ================================ */
     addContact(contact) {
+        if (!contact?.id ||
+            !contact?.publicKey ||
+            !contact?.fingerprint ||
+            !contact?.mlKey) {
+            throw new MajikContactDirectoryError("Invalid contact");
+        }
         if (!(contact instanceof MajikContact)) {
             throw new MajikContactDirectoryError("Invalid contact instance");
         }
@@ -125,6 +121,16 @@ export class MajikContactDirectory {
     hasContact(id) {
         return this.contacts.has(id);
     }
+    /**
+     * Checks if a contact exists by their public key (base64)
+     */
+    async hasContactByPublicKeyBase64(publicKeyBase64) {
+        if (!publicKeyBase64 || typeof publicKeyBase64 !== "string") {
+            throw new MajikContactDirectoryError("Public key must be a non-empty base64 string");
+        }
+        const contact = await this.getContactByPublicKeyBase64(publicKeyBase64);
+        return contact !== undefined;
+    }
     clear() {
         this.contacts.clear();
         this.fingerprintMap.clear();
@@ -174,7 +180,7 @@ export class MajikContactDirectory {
                 // Fallback: create a raw-key wrapper when the browser does not support the namedCurve
                 publicKey = { raw: new Uint8Array(raw) };
             }
-            const contact = MajikContact.create(item.id, publicKey, item.mlKey, item.fingerprint, item.meta);
+            const contact = MajikContact.create(item.id, publicKey, item.mlKey, item.fingerprint, item.meta, item.edPublicKeyBase64, item.mlDsaPublicKeyBase64);
             this.contacts.set(contact.id, contact);
             this.fingerprintMap.set(contact.fingerprint, contact.id);
         }

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

@@ -0,0 +1,186 @@
+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;
+    clear(): this;
+    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" | "color">>): 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;
+}