@fabriktor/fx 0.0.31 → 0.0.32

package/dist/src/calls/calls.js

@@ -3,7 +3,9 @@
 // Licensed under the Apache License, Version 2.0 (the "License"); you may
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
-import { errVideoTokenMintFailed } from "../core/err.js";
+import { errResolveFailed } from "../core/err.js";
+const resourceVideoToken = "video_token";
+const msgUnableToMintVideoToken = "Unable to mint video token.";
 export class CallsFX {
     calls;
     notifications;
@@ -26,10 +28,14 @@ export class CallsFX {
     }
     async requireVideoToken(opts) {
         const out = await this.calls.mintVideoToken(opts);
-        if (out.value === undefined || out.value.trim() === "") {
-            throw errVideoTokenMintFailed();
+        const token = out.value?.trim();
+        if (token === undefined || token === "") {
+            throw errResolveFailed({
+                resource: resourceVideoToken,
+                msg: msgUnableToMintVideoToken,
+            });
         }
-        return out.value;
+        return token;
     }
 }
 export function newCallsFX(opts) {

package/dist/src/chat/chat.d.ts

@@ -0,0 +1,89 @@
+import { type Chat, type ChatRoom, type ChatRoomMember, type PLChatReact } from "@fabriktor/schema";
+import type { ChatOperator, WSCloseHandler, WSConnection, WSErrorHandler, WSMessageHandler } from "@fabriktor/client";
+export type ChatFXOptions = {
+    chat: ChatOperator;
+};
+export type LatestChatsOptions = {
+    chat_room_id: string;
+    page?: number;
+    per_page?: number;
+};
+export type LatestChatsCursor = {
+    chat_room_id: string;
+    next_page: number;
+    per_page: number;
+    done: boolean;
+};
+export type NextLatestChatsOptions = {
+    cursor: LatestChatsCursor;
+};
+export type LatestChatsPage = {
+    chats: Chat[];
+    page: number;
+    per_page: number;
+    total_count?: number;
+    last_page?: number;
+    has_more: boolean;
+    next_cursor: LatestChatsCursor;
+};
+export type ChatRoomMembersOptions = {
+    chat_room_id: string;
+};
+export type MyChatRoomMembersOptions = {
+    owner_id: string;
+};
+export type OpenChatRoomOptions = {
+    owner_id: string;
+    chat_room_id: string;
+    per_page?: number;
+    on_chat: WSMessageHandler<Chat>;
+    on_chat_room: WSMessageHandler<ChatRoom>;
+    on_error?: WSErrorHandler;
+    on_close?: WSCloseHandler;
+};
+export type OpenGlobalChatRoomsOptions = {
+    owner_id: string;
+    on_chat_room: WSMessageHandler<ChatRoom>;
+    on_error?: WSErrorHandler;
+    on_close?: WSCloseHandler;
+};
+export type ReactUploadedChatOptions = {
+    chat: Chat;
+    reaction: PLChatReact;
+};
+export type ChatRoomSession = {
+    latest: LatestChatsPage;
+    chats_ws: WSConnection;
+    chat_room_ws: WSConnection;
+    closeNormal(reason?: string): void;
+    closeLeavingPage(reason?: string): void;
+};
+export type GlobalChatRoomsSession = {
+    members: ChatRoomMember[];
+    chat_rooms_ws: WSConnection;
+    closeNormal(reason?: string): void;
+    closeLeavingPage(reason?: string): void;
+};
+export interface ChatFXOperator {
+    newLatestChatsCursor(opts: LatestChatsOptions): LatestChatsCursor;
+    latestChats(opts: LatestChatsOptions): Promise<LatestChatsPage>;
+    nextLatestChats(opts: NextLatestChatsOptions): Promise<LatestChatsPage>;
+    chatRoomMembers(opts: ChatRoomMembersOptions): Promise<ChatRoomMember[]>;
+    myChatRoomMembers(opts: MyChatRoomMembersOptions): Promise<ChatRoomMember[]>;
+    openChatRoom(opts: OpenChatRoomOptions): Promise<ChatRoomSession>;
+    openGlobalChatRooms(opts: OpenGlobalChatRoomsOptions): Promise<GlobalChatRoomsSession>;
+    reactUploadedChat(opts: ReactUploadedChatOptions): Promise<void>;
+}
+export declare class ChatFX implements ChatFXOperator {
+    private chat;
+    constructor(opts: ChatFXOptions);
+    newLatestChatsCursor(opts: LatestChatsOptions): LatestChatsCursor;
+    latestChats(opts: LatestChatsOptions): Promise<LatestChatsPage>;
+    nextLatestChats(opts: NextLatestChatsOptions): Promise<LatestChatsPage>;
+    chatRoomMembers(opts: ChatRoomMembersOptions): Promise<ChatRoomMember[]>;
+    myChatRoomMembers(opts: MyChatRoomMembersOptions): Promise<ChatRoomMember[]>;
+    openChatRoom(opts: OpenChatRoomOptions): Promise<ChatRoomSession>;
+    openGlobalChatRooms(opts: OpenGlobalChatRoomsOptions): Promise<GlobalChatRoomsSession>;
+    reactUploadedChat(opts: ReactUploadedChatOptions): Promise<void>;
+}
+export declare function newChatFX(opts: ChatFXOptions): ChatFX;

package/dist/src/chat/chat.js

@@ -0,0 +1,194 @@
+// Copyright (C) Fabriktor, Inc. 2025-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+import { SearchPageKey, SearchPerPageKey, SearchResultResultsKey, } from "@fabriktor/schema";
+import { errValidation } from "../core/err.js";
+const firstPage = 1;
+const defaultPerPage = 30;
+const closeCodeNormal = 1000;
+const closeCodeLeavingPage = 1001;
+const msgChatObjectsUploading = "Cannot react to a chat while objects are still uploading.";
+export class ChatFX {
+    chat;
+    constructor(opts) {
+        this.chat = opts.chat;
+    }
+    newLatestChatsCursor(opts) {
+        return {
+            chat_room_id: opts.chat_room_id,
+            next_page: normalizePage(opts.page),
+            per_page: normalizePerPage(opts.per_page),
+            done: false,
+        };
+    }
+    async latestChats(opts) {
+        const page = normalizePage(opts.page);
+        const per_page = normalizePerPage(opts.per_page);
+        const raw = await this.chat.searchManyChats({
+            query: {
+                chat_room_id: opts.chat_room_id,
+                [SearchPageKey]: page,
+                [SearchPerPageKey]: per_page,
+            },
+        });
+        return latestChatsPage({
+            chat_room_id: opts.chat_room_id,
+            page,
+            per_page,
+            raw,
+        });
+    }
+    async nextLatestChats(opts) {
+        if (opts.cursor.done) {
+            return emptyLatestChatsPage(opts.cursor);
+        }
+        return await this.latestChats({
+            chat_room_id: opts.cursor.chat_room_id,
+            page: opts.cursor.next_page,
+            per_page: opts.cursor.per_page,
+        });
+    }
+    async chatRoomMembers(opts) {
+        const out = await this.chat.queryChatRoomMembers({
+            query: {
+                chat_room_id: opts.chat_room_id,
+            },
+        });
+        return out.value ?? [];
+    }
+    async myChatRoomMembers(opts) {
+        const out = await this.chat.queryChatRoomMembers({
+            query: {
+                owner_id: opts.owner_id,
+            },
+        });
+        return out.value ?? [];
+    }
+    async openChatRoom(opts) {
+        const latest = await this.latestChats({
+            chat_room_id: opts.chat_room_id,
+            per_page: opts.per_page,
+        });
+        const chats_ws = await this.chat.wsChats({
+            owner_id: opts.owner_id,
+            chat_room_id: opts.chat_room_id,
+            on_message: opts.on_chat,
+            on_error: opts.on_error,
+            on_close: opts.on_close,
+        });
+        const chat_room_ws = await this.chat.wsChatRoom({
+            id: opts.chat_room_id,
+            on_message: opts.on_chat_room,
+            on_error: opts.on_error,
+            on_close: opts.on_close,
+        });
+        return {
+            latest,
+            chats_ws,
+            chat_room_ws,
+            closeNormal(reason) {
+                closeWS([chats_ws, chat_room_ws], closeCodeNormal, reason);
+            },
+            closeLeavingPage(reason) {
+                closeWS([chats_ws, chat_room_ws], closeCodeLeavingPage, reason);
+            },
+        };
+    }
+    async openGlobalChatRooms(opts) {
+        const members = await this.myChatRoomMembers({
+            owner_id: opts.owner_id,
+        });
+        const chat_rooms_ws = await this.chat.wsMineChatRooms({
+            owner_id: opts.owner_id,
+            on_message: opts.on_chat_room,
+            on_error: opts.on_error,
+            on_close: opts.on_close,
+        });
+        return {
+            members,
+            chat_rooms_ws,
+            closeNormal(reason) {
+                closeWS([chat_rooms_ws], closeCodeNormal, reason);
+            },
+            closeLeavingPage(reason) {
+                closeWS([chat_rooms_ws], closeCodeLeavingPage, reason);
+            },
+        };
+    }
+    async reactUploadedChat(opts) {
+        if (opts.chat.has_objects && !opts.chat.objects_uploaded) {
+            throw errValidation({
+                field: "chat_id",
+                msg: msgChatObjectsUploading,
+            });
+        }
+        await this.chat.reactChat(opts.reaction);
+    }
+}
+export function newChatFX(opts) {
+    return new ChatFX(opts);
+}
+function latestChatsPage(opts) {
+    const value = opts.raw.value;
+    const chats = value?.[SearchResultResultsKey] ?? [];
+    const total_count = value?.total_count;
+    const last_page = value?.last_page;
+    const has_more = hasMoreChats({
+        chats,
+        page: opts.page,
+        per_page: opts.per_page,
+        total_count,
+        last_page,
+    });
+    return {
+        chats,
+        page: opts.page,
+        per_page: opts.per_page,
+        total_count,
+        last_page,
+        has_more,
+        next_cursor: {
+            chat_room_id: opts.chat_room_id,
+            next_page: has_more ? opts.page + 1 : opts.page,
+            per_page: opts.per_page,
+            done: !has_more,
+        },
+    };
+}
+function emptyLatestChatsPage(cursor) {
+    return {
+        chats: [],
+        page: cursor.next_page,
+        per_page: cursor.per_page,
+        has_more: false,
+        next_cursor: cursor,
+    };
+}
+function hasMoreChats(opts) {
+    if (opts.last_page !== undefined) {
+        return opts.page < opts.last_page;
+    }
+    if (opts.total_count !== undefined) {
+        return opts.page * opts.per_page < opts.total_count;
+    }
+    return opts.chats.length >= opts.per_page;
+}
+function closeWS(conns, code, reason) {
+    for (const conn of conns) {
+        conn.close(code, reason);
+    }
+}
+function normalizePage(v) {
+    if (v === undefined || !Number.isFinite(v)) {
+        return firstPage;
+    }
+    return Math.max(firstPage, Math.trunc(v));
+}
+function normalizePerPage(v) {
+    if (v === undefined || !Number.isFinite(v)) {
+        return defaultPerPage;
+    }
+    return Math.max(1, Math.trunc(v));
+}

package/dist/src/contacts/contacts.d.ts

@@ -0,0 +1,67 @@
+import { Friend, Hired, Manager, Na, OldHire, type Contact, type ID, type OperationResult } from "@fabriktor/schema";
+import type { ContactsOperator } from "@fabriktor/client";
+export type ContactRelation = typeof Na | typeof Friend | typeof OldHire | typeof Hired | typeof Manager;
+export type ActiveContactRelation = typeof Friend | typeof Hired | typeof Manager;
+export type ContactsFXOptions = {
+    contacts: ContactsOperator;
+};
+export type LoadContactIndexOptions = {
+    owner_id: string;
+};
+export type ContactIndex = {
+    contacts: Contact[];
+    peer_ids: Set<string>;
+};
+export type PresenceActiveHandler = (active_ids: ID[]) => void;
+export type PresenceErrorHandler = (err: unknown) => void;
+export type StartPresenceOptions = {
+    on_active: PresenceActiveHandler;
+    on_error?: PresenceErrorHandler;
+};
+export type PresenceSession = {
+    stop(): void;
+};
+export type SendFriendRequestOptions = {
+    contact_id: string;
+};
+export type RequestRelationUpgradeOptions = {
+    contact: Contact;
+    requested_relation: ActiveContactRelation;
+};
+export type DowngradeRelationOptions = {
+    contact: Contact;
+    relation: ActiveContactRelation;
+};
+export type AcceptContactRequestOptions = {
+    contact: Contact;
+};
+export type RejectContactRequestOptions = {
+    contact: Contact;
+};
+export type EndHireRelationOptions = {
+    contact: Contact;
+};
+export interface ContactsFXOperator {
+    loadContactIndex(opts: LoadContactIndexOptions): Promise<ContactIndex>;
+    startPresence(opts: StartPresenceOptions): Promise<PresenceSession>;
+    sendFriendRequest(opts: SendFriendRequestOptions): Promise<OperationResult>;
+    requestRelationUpgrade(opts: RequestRelationUpgradeOptions): Promise<OperationResult>;
+    downgradeRelation(opts: DowngradeRelationOptions): Promise<OperationResult>;
+    acceptContactRequest(opts: AcceptContactRequestOptions): Promise<OperationResult>;
+    rejectContactRequest(opts: RejectContactRequestOptions): Promise<OperationResult>;
+    endHireRelation(opts: EndHireRelationOptions): Promise<OperationResult>;
+}
+export declare class ContactsFX implements ContactsFXOperator {
+    private contacts;
+    constructor(opts: ContactsFXOptions);
+    loadContactIndex(opts: LoadContactIndexOptions): Promise<ContactIndex>;
+    startPresence(opts: StartPresenceOptions): Promise<PresenceSession>;
+    sendFriendRequest(opts: SendFriendRequestOptions): Promise<OperationResult>;
+    requestRelationUpgrade(opts: RequestRelationUpgradeOptions): Promise<OperationResult>;
+    downgradeRelation(opts: DowngradeRelationOptions): Promise<OperationResult>;
+    acceptContactRequest(opts: AcceptContactRequestOptions): Promise<OperationResult>;
+    rejectContactRequest(opts: RejectContactRequestOptions): Promise<OperationResult>;
+    endHireRelation(opts: EndHireRelationOptions): Promise<OperationResult>;
+    private replaceContact;
+}
+export declare function newContactsFX(opts: ContactsFXOptions): ContactsFX;

package/dist/src/contacts/contacts.js

@@ -0,0 +1,179 @@
+// Copyright (C) Fabriktor, Inc. 2025-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+import { Friend, Na, OldHire, } from "@fabriktor/schema";
+import { errRequired, errValidation } from "../core/err.js";
+const presenceIntervalMS = 120_000;
+const msgOwnerIDRequired = "Owner ID is required.";
+const msgContactIDRequired = "Contact ID is required.";
+const msgRelationUpgradeInvalid = "Requested relation must be higher than the current relation.";
+const msgRelationDowngradeInvalid = "Requested relation must be lower than the current relation.";
+const msgPendingRelationRequired = "Contact request does not contain a pending relation.";
+export class ContactsFX {
+    contacts;
+    constructor(opts) {
+        this.contacts = opts.contacts;
+    }
+    async loadContactIndex(opts) {
+        const owner_id = opts.owner_id.trim();
+        if (owner_id === "") {
+            throw errRequired({
+                field: "owner_id",
+                msg: msgOwnerIDRequired,
+            });
+        }
+        const out = await this.contacts.findContacts();
+        const contacts = out.value ?? [];
+        const peer_ids = new Set();
+        for (const contact of contacts) {
+            const peer_id = contactPeerID(contact, owner_id);
+            if (peer_id !== undefined) {
+                peer_ids.add(peer_id);
+            }
+        }
+        return {
+            contacts,
+            peer_ids,
+        };
+    }
+    async startPresence(opts) {
+        const initial = await this.contacts.signal();
+        opts.on_active(initial.value ?? []);
+        let stopped = false;
+        let running = false;
+        const tick = async () => {
+            if (stopped || running) {
+                return;
+            }
+            running = true;
+            try {
+                const out = await this.contacts.signal();
+                if (!stopped) {
+                    opts.on_active(out.value ?? []);
+                }
+            }
+            catch (err) {
+                if (!stopped) {
+                    opts.on_error?.(err);
+                }
+            }
+            finally {
+                running = false;
+            }
+        };
+        const timer = setInterval(() => {
+            void tick();
+        }, presenceIntervalMS);
+        return {
+            stop() {
+                if (stopped) {
+                    return;
+                }
+                stopped = true;
+                clearInterval(timer);
+            },
+        };
+    }
+    async sendFriendRequest(opts) {
+        const contact_id = opts.contact_id.trim();
+        if (contact_id === "") {
+            throw errRequired({
+                field: "contact_id",
+                msg: msgContactIDRequired,
+            });
+        }
+        return await this.contacts.insertOneContact({
+            in: {
+                contact_id,
+                is_pending: true,
+                relation: Na,
+                requested_relation: Friend,
+                is_archived: false,
+            },
+        });
+    }
+    async requestRelationUpgrade(opts) {
+        if (opts.requested_relation <= opts.contact.relation) {
+            throw errValidation({
+                field: "requested_relation",
+                msg: msgRelationUpgradeInvalid,
+            });
+        }
+        return await this.replaceContact(opts.contact, {
+            is_pending: true,
+            relation: opts.contact.relation,
+            requested_relation: opts.requested_relation,
+            is_archived: false,
+        });
+    }
+    async downgradeRelation(opts) {
+        if (opts.relation >= opts.contact.relation) {
+            throw errValidation({
+                field: "relation",
+                msg: msgRelationDowngradeInvalid,
+            });
+        }
+        return await this.replaceContact(opts.contact, {
+            is_pending: false,
+            relation: opts.relation,
+            requested_relation: Na,
+            is_archived: false,
+        });
+    }
+    async acceptContactRequest(opts) {
+        if (opts.contact.requested_relation === Na) {
+            throw errValidation({
+                field: "contact",
+                msg: msgPendingRelationRequired,
+            });
+        }
+        return await this.replaceContact(opts.contact, {
+            is_pending: false,
+            relation: opts.contact.requested_relation,
+            requested_relation: Na,
+            is_archived: false,
+        });
+    }
+    async rejectContactRequest(opts) {
+        return await this.replaceContact(opts.contact, {
+            is_archived: true,
+        });
+    }
+    async endHireRelation(opts) {
+        return await this.replaceContact(opts.contact, {
+            is_pending: false,
+            relation: OldHire,
+            requested_relation: Na,
+            is_archived: false,
+        });
+    }
+    async replaceContact(contact, overrides) {
+        return await this.contacts.replaceOneContact({
+            id: contact.id,
+            in: {
+                contact_id: contact.contact_id,
+                is_pending: contact.is_pending,
+                relation: contact.relation,
+                requested_relation: contact.requested_relation,
+                is_archived: contact.is_archived,
+                ...overrides,
+            },
+        });
+    }
+}
+export function newContactsFX(opts) {
+    return new ContactsFX(opts);
+}
+function contactPeerID(contact, owner_id) {
+    const contact_owner_id = contact.owner_id.trim();
+    const contact_id = contact.contact_id.trim();
+    if (contact_owner_id === owner_id && contact_id !== "") {
+        return contact_id;
+    }
+    if (contact_id === owner_id && contact_owner_id !== "") {
+        return contact_owner_id;
+    }
+    return undefined;
+}

package/dist/src/core/err.d.ts

@@ -29,11 +29,6 @@ export type ResolveFailedFXErrOptions<T extends object = Record<string, unknown>
     field?: FieldOf<T>;
     cause?: unknown;
 };
-export type UsernameInvalidFXErrOptions<T extends object = Record<string, unknown>> = {
-    field: FieldOf<T>;
-    msg: string;
-    cause?: unknown;
-};
 type FXErrRuntimeOptions = {
     kind: FXErrKind;
     msg: string;
@@ -52,11 +47,6 @@ export declare function errFX<T extends object = Record<string, unknown>>(opts:
 export declare function errRequired<T extends object = Record<string, unknown>>(opts: RequiredFXErrOptions<T>): FXErr;
 export declare function errValidation<T extends object = Record<string, unknown>>(opts: ValidationFXErrOptions<T>): FXErr;
 export declare function errResolveFailed<T extends object = Record<string, unknown>>(opts: ResolveFailedFXErrOptions<T>): FXErr;
-export declare function errUsernameResolveFailed<T extends object = Record<string, unknown>>(field?: FieldOf<T>): FXErr;
-export declare function errVideoTokenMintFailed(): FXErr;
-export declare function errUsernameInvalid<T extends object = Record<string, unknown>>(opts: UsernameInvalidFXErrOptions<T>): FXErr;
-export declare function errPhoneRequired<T extends object = Record<string, unknown>>(field: FieldOf<T>): FXErr;
-export declare function errPhoneCodeRequired<T extends object = Record<string, unknown>>(field: FieldOf<T>): FXErr;
 export declare function errUnknown(cause: unknown): FXErr;
 export declare function isFXErr(err: unknown): err is FXErr;
 export declare function fxErrMessage(err: unknown): string;

package/dist/src/core/err.js

@@ -4,12 +4,6 @@
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 const msgUnknownFXErr = "Unknown FX error.";
-const msgUnableToResolveUsername = "Unable to resolve username.";
-const msgUnableToMintVideoToken = "Unable to mint video token.";
-const msgPhoneRequired = "Phone number is required.";
-const msgPhoneCodeRequired = "Verification code is required.";
-const resourceUsername = "username";
-const resourceVideoToken = "video_token";
 export const FXErrKind = {
     Required: "required",
     Validation: "validation",
@@ -64,38 +58,6 @@ export function errResolveFailed(opts) {
         cause: opts.cause,
     });
 }
-export function errUsernameResolveFailed(field) {
-    return errResolveFailed({
-        resource: resourceUsername,
-        field,
-        msg: msgUnableToResolveUsername,
-    });
-}
-export function errVideoTokenMintFailed() {
-    return errResolveFailed({
-        resource: resourceVideoToken,
-        msg: msgUnableToMintVideoToken,
-    });
-}
-export function errUsernameInvalid(opts) {
-    return errValidation({
-        field: opts.field,
-        msg: opts.msg,
-        cause: opts.cause,
-    });
-}
-export function errPhoneRequired(field) {
-    return errRequired({
-        field,
-        msg: msgPhoneRequired,
-    });
-}
-export function errPhoneCodeRequired(field) {
-    return errRequired({
-        field,
-        msg: msgPhoneCodeRequired,
-    });
-}
 export function errUnknown(cause) {
     if (isFXErr(cause)) {
         return cause;

package/dist/src/fx.d.ts

@@ -1,19 +1,26 @@
-import type { BillableOperator, CallsOperator, NotificationsOperator, PreferencesOperator, TmpPhonesOperator, TmpUsernamesOperator, UsersOperator } from "@fabriktor/client";
+import type { BillableOperator, CallsOperator, ChatOperator, ConnectionsOperator, ContactsOperator, NotificationsOperator, PreferencesOperator, StorageOperator, TmpPhonesOperator, TmpUsernamesOperator, UsersOperator } from "@fabriktor/client";
 import type { AuthOperator } from "./auth/auth.js";
 import type { BillableFX, BillableFXOperator } from "./billable/billable.js";
 import type { CallsFX, CallsFXOperator } from "./calls/calls.js";
+import type { ChatFX, ChatFXOperator } from "./chat/chat.js";
+import type { ContactsFX, ContactsFXOperator } from "./contacts/contacts.js";
 import type { PreferencesFX, PreferencesFXOperator } from "./preferences/preferences.js";
 import type { SessionFX, SessionFXOperator } from "./session/session.js";
+import type { StorageFX, StorageFXOperator } from "./storage/storage.js";
 import type { UsersFX, UsersFXOperator } from "./users/users.js";
 export type FXOptions = {
     auth: AuthOperator;
     billable: BillableOperator;
     calls: CallsOperator;
+    chat: ChatOperator;
+    connections: ConnectionsOperator;
+    contacts: ContactsOperator;
     notifications: NotificationsOperator;
-    users: UsersOperator;
-    tmp_usernames: TmpUsernamesOperator;
-    tmp_phones: TmpPhonesOperator;
     preferences: PreferencesOperator;
+    storage: StorageOperator;
+    tmp_phones: TmpPhonesOperator;
+    tmp_usernames: TmpUsernamesOperator;
+    users: UsersOperator;
 };
 export type DefaultFXOptions = {
     base_url: string;
@@ -22,16 +29,22 @@ export type DefaultFXOptions = {
 export interface FXOperator {
     billable: BillableFXOperator;
     calls: CallsFXOperator;
-    users: UsersFXOperator;
-    session: SessionFXOperator;
+    chat: ChatFXOperator;
+    contacts: ContactsFXOperator;
     preferences: PreferencesFXOperator;
+    session: SessionFXOperator;
+    storage: StorageFXOperator;
+    users: UsersFXOperator;
 }
 export declare class FX implements FXOperator {
     billable: BillableFX;
     calls: CallsFX;
-    users: UsersFX;
-    session: SessionFX;
+    chat: ChatFX;
+    contacts: ContactsFX;
     preferences: PreferencesFX;
+    session: SessionFX;
+    storage: StorageFX;
+    users: UsersFX;
     constructor(opts: FXOptions);
 }
 export declare function newFX(opts: FXOptions): FX;

package/dist/src/fx.js

@@ -1,20 +1,26 @@
-// Copyright (C) Fabriktor, Inc. 2025-present.
+// Copyright (C) Fab// Copyright (C) Fabriktor, Inc. 2025-present.
 //
 // Licensed under the Apache License, Version 2.0 (the "License"); you may
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
-import { newBillableClient, newCallsClient, newHTTPClient, newNotificationsClient, newPreferencesClient, newTmpPhonesClient, newTmpUsernamesClient, newUsersClient, } from "@fabriktor/client";
+import { newBillableClient, newCallsClient, newChatClient, newConnectionsClient, newContactsClient, newHTTPClient, newNotificationsClient, newPreferencesClient, newStorageClient, newTmpPhonesClient, newTmpUsernamesClient, newUsersClient, } from "@fabriktor/client";
 import { newBillableFX } from "./billable/billable.js";
 import { newCallsFX } from "./calls/calls.js";
+import { newChatFX } from "./chat/chat.js";
+import { newContactsFX } from "./contacts/contacts.js";
 import { newPreferencesFX } from "./preferences/preferences.js";
 import { newSessionFX } from "./session/session.js";
+import { newStorageFX } from "./storage/storage.js";
 import { newUsersFX } from "./users/users.js";
 export class FX {
     billable;
     calls;
-    users;
-    session;
+    chat;
+    contacts;
     preferences;
+    session;
+    storage;
+    users;
     constructor(opts) {
         this.billable = newBillableFX({
             billable: opts.billable,
@@ -23,16 +29,26 @@ export class FX {
             calls: opts.calls,
             notifications: opts.notifications,
         });
+        this.chat = newChatFX({
+            chat: opts.chat,
+        });
+        this.contacts = newContactsFX({
+            contacts: opts.contacts,
+        });
+        this.preferences = newPreferencesFX({
+            preferences: opts.preferences,
+        });
+        this.storage = newStorageFX({
+            storage: opts.storage,
+        });
         this.users = newUsersFX({
             users: opts.users,
             tmp_usernames: opts.tmp_usernames,
             tmp_phones: opts.tmp_phones,
         });
-        this.preferences = newPreferencesFX({
-            preferences: opts.preferences,
-        });
         this.session = newSessionFX({
             auth: opts.auth,
+            connections: opts.connections,
             users: opts.users,
             users_fx: this.users,
         });
@@ -56,17 +72,32 @@ export function newDefaultFX(opts) {
             base_url: opts.base_url,
             get_token,
         }),
+        chat: newChatClient({
+            http,
+            base_url: opts.base_url,
+            get_token,
+        }),
+        connections: newConnectionsClient({
+            http,
+            base_url: opts.base_url,
+            get_token,
+        }),
+        contacts: newContactsClient({
+            http,
+            base_url: opts.base_url,
+            get_token,
+        }),
         notifications: newNotificationsClient({
             http,
             base_url: opts.base_url,
             get_token,
         }),
-        users: newUsersClient({
+        preferences: newPreferencesClient({
             http,
             base_url: opts.base_url,
             get_token,
         }),
-        tmp_usernames: newTmpUsernamesClient({
+        storage: newStorageClient({
             http,
             base_url: opts.base_url,
             get_token,
@@ -76,7 +107,12 @@ export function newDefaultFX(opts) {
             base_url: opts.base_url,
             get_token,
         }),
-        preferences: newPreferencesClient({
+        tmp_usernames: newTmpUsernamesClient({
+            http,
+            base_url: opts.base_url,
+            get_token,
+        }),
+        users: newUsersClient({
             http,
             base_url: opts.base_url,
             get_token,

package/dist/src/index.d.ts

@@ -1,10 +1,13 @@
 export * from "./auth/auth.js";
 export * from "./billable/billable.js";
 export * from "./calls/calls.js";
+export * from "./chat/chat.js";
+export * from "./contacts/contacts.js";
 export * from "./core/err.js";
 export * from "./fx.js";
 export * from "./preferences/preferences.js";
 export * from "./session/session.js";
+export * from "./storage/storage.js";
 export * from "./users/phone.js";
 export * from "./users/username.js";
 export * from "./users/users.js";

package/dist/src/index.js

@@ -1,10 +1,13 @@
 export * from "./auth/auth.js";
 export * from "./billable/billable.js";
 export * from "./calls/calls.js";
+export * from "./chat/chat.js";
+export * from "./contacts/contacts.js";
 export * from "./core/err.js";
 export * from "./fx.js";
 export * from "./preferences/preferences.js";
 export * from "./session/session.js";
+export * from "./storage/storage.js";
 export * from "./users/phone.js";
 export * from "./users/username.js";
 export * from "./users/users.js";

package/dist/src/session/session.d.ts

@@ -1,18 +1,27 @@
-import type { InUser, PLUsersForgotPassword, PLUsersSignInLink, PLUsersVerifyEmail, UpsertResult } from "@fabriktor/schema";
-import type { BootstrapOptions, OperationResultOf, UsersOperator } from "@fabriktor/client";
+import type { InConnection, InUser, PLUsersForgotPassword, PLUsersSignInLink, PLUsersVerifyEmail, UpsertResult } from "@fabriktor/schema";
+import type { BootstrapOptions, ConnectionsOperator, OperationResultOf, UsersOperator } from "@fabriktor/client";
 import type { AuthEmailOptions, AuthOperator } from "../auth/auth.js";
 import type { UsersFXOperator } from "../users/users.js";
-export type SignInMode = "email" | "username";
+export declare const SignInMode: {
+    readonly Email: "email";
+    readonly Username: "username";
+};
+export type SignInMode = (typeof SignInMode)[keyof typeof SignInMode];
 export type SignInOptions = {
     mode: SignInMode;
     identifier: string;
     password: string;
+    connection: InConnection;
+};
+export type SignInWithEmailOptions = AuthEmailOptions & {
+    connection: InConnection;
 };
 export type SignUpAndBootstrapOptions = AuthEmailOptions & {
     in: InUser;
 };
 export type SessionFXOptions = {
     auth: AuthOperator;
+    connections: ConnectionsOperator;
     users: UsersOperator;
     users_fx: UsersFXOperator;
 };
@@ -21,7 +30,7 @@ export interface SessionFXOperator {
     finishSignUp(opts: BootstrapOptions): Promise<OperationResultOf<UpsertResult>>;
     signUpAndBootstrap(opts: SignUpAndBootstrapOptions): Promise<OperationResultOf<UpsertResult>>;
     signIn(opts: SignInOptions): Promise<void>;
-    signInWithEmail(opts: AuthEmailOptions): Promise<void>;
+    signInWithEmail(opts: SignInWithEmailOptions): Promise<void>;
     signOut(): Promise<void>;
     forgotPassword(opts: PLUsersForgotPassword): Promise<void>;
     sendSignInLink(opts: PLUsersSignInLink): Promise<void>;
@@ -30,6 +39,7 @@ export interface SessionFXOperator {
 }
 export declare class SessionFX implements SessionFXOperator {
     private auth;
+    private connections;
     private users;
     private users_fx;
     constructor(opts: SessionFXOptions);
@@ -37,7 +47,7 @@ export declare class SessionFX implements SessionFXOperator {
     finishSignUp(opts: BootstrapOptions): Promise<OperationResultOf<UpsertResult>>;
     signUpAndBootstrap(opts: SignUpAndBootstrapOptions): Promise<OperationResultOf<UpsertResult>>;
     signIn(opts: SignInOptions): Promise<void>;
-    signInWithEmail(opts: AuthEmailOptions): Promise<void>;
+    signInWithEmail(opts: SignInWithEmailOptions): Promise<void>;
     signOut(): Promise<void>;
     forgotPassword(opts: PLUsersForgotPassword): Promise<void>;
     sendSignInLink(opts: PLUsersSignInLink): Promise<void>;

package/dist/src/session/session.js

@@ -3,12 +3,18 @@
 // Licensed under the Apache License, Version 2.0 (the "License"); you may
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+export const SignInMode = {
+    Email: "email",
+    Username: "username",
+};
 export class SessionFX {
     auth;
+    connections;
     users;
     users_fx;
     constructor(opts) {
         this.auth = opts.auth;
+        this.connections = opts.connections;
         this.users = opts.users;
         this.users_fx = opts.users_fx;
     }
@@ -33,7 +39,7 @@ export class SessionFX {
         });
     }
     async signIn(opts) {
-        const email = opts.mode === "email"
+        const email = opts.mode === SignInMode.Email
             ? opts.identifier
             : await this.users_fx.resolveUsername({
                 username: opts.identifier,
@@ -41,10 +47,17 @@ export class SessionFX {
         await this.signInWithEmail({
             email,
             password: opts.password,
+            connection: opts.connection,
         });
     }
     async signInWithEmail(opts) {
-        await this.auth.signIn(opts);
+        await this.auth.signIn({
+            email: opts.email,
+            password: opts.password,
+        });
+        await this.connections.insertOneConnection({
+            in: opts.connection,
+        });
         await this.users.sync();
     }
     async signOut() {

package/dist/src/storage/storage.d.ts

@@ -0,0 +1,70 @@
+import { type Object as StorageObject, type PLStorageDownload, type RPStorageUpload } from "@fabriktor/schema";
+import type { OperationResultOf, StorageCollection, StorageOperator, StorageUploadFile, UploadStorageOptions, OptionalField } from "@fabriktor/client";
+export declare const StorageUploadModeration: {
+    readonly Clean: "clean";
+    readonly ContainsForbidden: "contains_forbidden";
+    readonly AllForbidden: "all_forbidden";
+};
+export type StorageUploadModeration = (typeof StorageUploadModeration)[keyof typeof StorageUploadModeration];
+export declare const StorageDualUploadStatus: {
+    readonly ChatOnly: "chat_only";
+    readonly Complete: "complete";
+    readonly Partial: "partial";
+};
+export type StorageDualUploadStatus = (typeof StorageDualUploadStatus)[keyof typeof StorageDualUploadStatus];
+export type StorageFXOptions = {
+    storage: StorageOperator;
+};
+export type UploadObjectsOptions = UploadStorageOptions & {
+    col: StorageCollection;
+};
+export type DownloadObjectsOptions = OptionalField<PLStorageDownload, "mime_prefix"> & {
+    col: StorageCollection;
+};
+export type UploadUserObjectsOptions = {
+    user_id: string;
+    uploader_id?: string;
+    full_quality?: boolean;
+    files: StorageUploadFile[];
+};
+export type UploadChatObjectsOptions = {
+    chat_id: string;
+    user_id?: string;
+    uploader_id?: string;
+    full_quality?: boolean;
+    files: StorageUploadFile[];
+    save_to_personal_box?: boolean;
+};
+export type StorageUploadResult = {
+    raw: OperationResultOf<RPStorageUpload>;
+    moderation: StorageUploadModeration;
+    contains_forbidden: boolean;
+    all_forbidden: boolean;
+};
+export type UploadChatObjectsResult = {
+    status: typeof StorageDualUploadStatus.ChatOnly;
+    chat: StorageUploadResult;
+} | {
+    status: typeof StorageDualUploadStatus.Complete;
+    chat: StorageUploadResult;
+    personal_box: StorageUploadResult;
+} | {
+    status: typeof StorageDualUploadStatus.Partial;
+    chat: StorageUploadResult;
+    personal_box_error: unknown;
+};
+export interface StorageFXOperator {
+    uploadObjects(opts: UploadObjectsOptions): Promise<StorageUploadResult>;
+    downloadObjects(opts: DownloadObjectsOptions): Promise<OperationResultOf<StorageObject[]>>;
+    uploadUserObjects(opts: UploadUserObjectsOptions): Promise<StorageUploadResult>;
+    uploadChatObjects(opts: UploadChatObjectsOptions): Promise<UploadChatObjectsResult>;
+}
+export declare class StorageFX implements StorageFXOperator {
+    private storage;
+    constructor(opts: StorageFXOptions);
+    uploadObjects(opts: UploadObjectsOptions): Promise<StorageUploadResult>;
+    downloadObjects(opts: DownloadObjectsOptions): Promise<OperationResultOf<StorageObject[]>>;
+    uploadUserObjects(opts: UploadUserObjectsOptions): Promise<StorageUploadResult>;
+    uploadChatObjects(opts: UploadChatObjectsOptions): Promise<UploadChatObjectsResult>;
+}
+export declare function newStorageFX(opts: StorageFXOptions): StorageFX;

package/dist/src/storage/storage.js

@@ -0,0 +1,225 @@
+// Copyright (C) Fabriktor, Inc. 2025-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+import { ColStorageChat, ColStorageUsers, } from "@fabriktor/schema";
+import { errRequired, errValidation } from "../core/err.js";
+const maxUploadFiles = 20;
+const maxUploadBytes = 1024 * 1024 * 1024;
+const mimePrefixAll = "";
+const extensionHEIC = ".heic";
+const extensionHEIF = ".heif";
+const mimeImageHEIC = "image/heic";
+const mimeImageHEIF = "image/heif";
+const mimeImageHEICSequence = "image/heic-sequence";
+const mimeImageHEIFSequence = "image/heif-sequence";
+const msgOwnerIDRequired = "Owner ID is required.";
+const msgChatIDRequired = "Chat ID is required.";
+const msgUserIDRequired = "User ID is required.";
+const msgUploadFilesRequired = "At least one file is required.";
+const msgUploadTooManyFiles = "Upload supports at most 20 files.";
+const msgUploadTooLarge = "Combined upload size cannot exceed 1 GB.";
+const msgHEICUnsupported = "HEIC and HEIF files must be converted to JPEG or PNG before upload.";
+export const StorageUploadModeration = {
+    Clean: "clean",
+    ContainsForbidden: "contains_forbidden",
+    AllForbidden: "all_forbidden",
+};
+export const StorageDualUploadStatus = {
+    ChatOnly: "chat_only",
+    Complete: "complete",
+    Partial: "partial",
+};
+export class StorageFX {
+    storage;
+    constructor(opts) {
+        this.storage = opts.storage;
+    }
+    async uploadObjects(opts) {
+        validateUpload(opts);
+        const out = await this.storage.upload(opts.col, {
+            owner_id: opts.owner_id,
+            uploader_id: opts.uploader_id,
+            full_quality: opts.full_quality,
+            files: opts.files,
+        });
+        return uploadResult(out);
+    }
+    async downloadObjects(opts) {
+        const owner_id = opts.owner_id.trim();
+        if (owner_id === "") {
+            throw errRequired({
+                field: "owner_id",
+                msg: msgOwnerIDRequired,
+            });
+        }
+        const { col, mime_prefix, ...input } = opts;
+        return await this.storage.download(col, {
+            ...input,
+            owner_id,
+            mime_prefix: mime_prefix?.trim() ?? mimePrefixAll,
+        });
+    }
+    async uploadUserObjects(opts) {
+        const user_id = opts.user_id.trim();
+        if (user_id === "") {
+            throw errRequired({
+                field: "user_id",
+                msg: msgUserIDRequired,
+            });
+        }
+        return await this.uploadObjects({
+            col: ColStorageUsers,
+            owner_id: user_id,
+            uploader_id: opts.uploader_id,
+            full_quality: opts.full_quality,
+            files: opts.files,
+        });
+    }
+    async uploadChatObjects(opts) {
+        const chat_id = opts.chat_id.trim();
+        if (chat_id === "") {
+            throw errRequired({
+                field: "chat_id",
+                msg: msgChatIDRequired,
+            });
+        }
+        let personal_box_user_id;
+        if (opts.save_to_personal_box) {
+            const user_id = opts.user_id?.trim() ?? "";
+            if (user_id === "") {
+                throw errRequired({
+                    field: "user_id",
+                    msg: msgUserIDRequired,
+                });
+            }
+            personal_box_user_id = user_id;
+        }
+        const chat = await this.uploadObjects({
+            col: ColStorageChat,
+            owner_id: chat_id,
+            uploader_id: opts.uploader_id,
+            full_quality: opts.full_quality,
+            files: opts.files,
+        });
+        if (personal_box_user_id === undefined) {
+            return {
+                status: StorageDualUploadStatus.ChatOnly,
+                chat,
+            };
+        }
+        try {
+            const personal_box = await this.uploadUserObjects({
+                user_id: personal_box_user_id,
+                uploader_id: opts.uploader_id,
+                full_quality: opts.full_quality,
+                files: opts.files,
+            });
+            return {
+                status: StorageDualUploadStatus.Complete,
+                chat,
+                personal_box,
+            };
+        }
+        catch (err) {
+            return {
+                status: StorageDualUploadStatus.Partial,
+                chat,
+                personal_box_error: err,
+            };
+        }
+    }
+}
+export function newStorageFX(opts) {
+    return new StorageFX(opts);
+}
+function validateUpload(opts) {
+    if (opts.owner_id.trim() === "") {
+        throw errRequired({
+            field: "owner_id",
+            msg: msgOwnerIDRequired,
+        });
+    }
+    if (opts.files.length === 0) {
+        throw errRequired({
+            field: "files",
+            msg: msgUploadFilesRequired,
+        });
+    }
+    if (opts.files.length > maxUploadFiles) {
+        throw errValidation({
+            field: "files",
+            msg: msgUploadTooManyFiles,
+        });
+    }
+    if (uploadSize(opts.files) > maxUploadBytes) {
+        throw errValidation({
+            field: "files",
+            msg: msgUploadTooLarge,
+        });
+    }
+    if (opts.files.some(isHEIC)) {
+        throw errValidation({
+            field: "files",
+            msg: msgHEICUnsupported,
+        });
+    }
+}
+function uploadSize(files) {
+    let out = 0;
+    for (const f of files) {
+        out += fileSize(f);
+    }
+    return out;
+}
+function fileSize(f) {
+    if ("blob" in f) {
+        return f.blob.size;
+    }
+    return f.size;
+}
+function isHEIC(f) {
+    const name = fileName(f).toLowerCase();
+    const mime = fileMIME(f).toLowerCase();
+    return (name.endsWith(extensionHEIC) ||
+        name.endsWith(extensionHEIF) ||
+        mime === mimeImageHEIC ||
+        mime === mimeImageHEIF ||
+        mime === mimeImageHEICSequence ||
+        mime === mimeImageHEIFSequence);
+}
+function fileName(f) {
+    if ("blob" in f) {
+        return f.filename;
+    }
+    return f.name;
+}
+function fileMIME(f) {
+    if ("blob" in f) {
+        return f.blob.type;
+    }
+    return f.type;
+}
+function uploadResult(raw) {
+    const contains_forbidden = raw.value?.contains_forbidden ?? false;
+    const all_forbidden = raw.value?.all_forbidden ?? false;
+    return {
+        raw,
+        moderation: uploadModeration({
+            contains_forbidden,
+            all_forbidden,
+        }),
+        contains_forbidden,
+        all_forbidden,
+    };
+}
+function uploadModeration(opts) {
+    if (opts.all_forbidden) {
+        return StorageUploadModeration.AllForbidden;
+    }
+    if (opts.contains_forbidden) {
+        return StorageUploadModeration.ContainsForbidden;
+    }
+    return StorageUploadModeration.Clean;
+}

package/dist/src/users/users.js

@@ -3,9 +3,13 @@
 // Licensed under the Apache License, Version 2.0 (the "License"); you may
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
-import { errPhoneCodeRequired, errPhoneRequired, errUsernameInvalid, errUsernameResolveFailed, } from "../core/err.js";
+import { errRequired, errResolveFailed, errValidation, } from "../core/err.js";
 import { normalizePhone, normalizePhoneCode, validatePhone, validatePhoneCode, } from "./phone.js";
 import { normalizeUsername, validateUsernameFormat } from "./username.js";
+const msgUnableToResolveUsername = "Unable to resolve username.";
+const msgPhoneRequired = "Phone number is required.";
+const msgPhoneCodeRequired = "Verification code is required.";
+const resourceUsername = "username";
 export class UsersFX {
     users;
     tmp_usernames;
@@ -30,10 +34,7 @@ export class UsersFX {
     async verifyUsername(opts) {
         const check = validateUsernameFormat(opts.to_validate);
         if (!check.valid) {
-            throw errUsernameInvalid({
-                field: "to_validate",
-                msg: check.error,
-            });
+            throw errUsernameInvalid("to_validate", check.error);
         }
         return await this.tmp_usernames.verify({
             words: opts.words,
@@ -73,3 +74,28 @@ export class UsersFX {
 export function newUsersFX(opts) {
     return new UsersFX(opts);
 }
+function errUsernameResolveFailed(field) {
+    return errResolveFailed({
+        resource: resourceUsername,
+        field,
+        msg: msgUnableToResolveUsername,
+    });
+}
+function errUsernameInvalid(field, msg) {
+    return errValidation({
+        field,
+        msg,
+    });
+}
+function errPhoneRequired(field) {
+    return errRequired({
+        field,
+        msg: msgPhoneRequired,
+    });
+}
+function errPhoneCodeRequired(field) {
+    return errRequired({
+        field,
+        msg: msgPhoneCodeRequired,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabriktor/fx",
-  "version": "0.0.31",
+  "version": "0.0.32",
   "description": "![Fabriktor Logo](./img/fabriktor-character.gif)",
   "type": "module",
   "exports": {
@@ -17,7 +17,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@fabriktor/client": "0.0.32",
-    "@fabriktor/schema": "0.0.27"
+    "@fabriktor/client": "0.0.38",
+    "@fabriktor/schema": "0.0.29"
   }
 }