@decentnetwork/peer 0.1.82 → 0.1.84

package/dist/compat/packet.d.ts

@@ -1,9 +1,16 @@
 export declare const PACKET_TYPE_USERINFO = 3;
 export declare const PACKET_TYPE_FRIEND_REQUEST = 6;
 export declare const PACKET_TYPE_MESSAGE = 33;
+export declare const PACKET_TYPE_INVITE_REQUEST = 34;
+export declare const PACKET_TYPE_INVITE_RESPONSE = 35;
 export declare const PACKET_TYPE_BULKMSG = 36;
 export declare const CARRIER_MAX_APP_MESSAGE_LEN = 1024;
 export declare const CARRIER_MAX_APP_BULKMSG_LEN: number;
+export declare const INVITE_DATA_UNIT = 1280;
+export declare const CARRIER_MAX_INVITE_DATA_LEN = 8192;
+export declare const CARRIER_MAX_BUNDLE_LEN = 511;
+export declare const CARRIER_MAX_EXTENSION_NAME_LEN = 31;
+export declare const CARRIER_EXTENSION_NAME = "carrier";
 export type UserInfoPacket = {
     type: typeof PACKET_TYPE_USERINFO;
     avatar: boolean;
@@ -34,7 +41,39 @@ export type BulkMsgPacket = {
     tid: bigint;
     data: Uint8Array;
 };
-export type CarrierPacket = UserInfoPacket | FriendRequestPacket | FriendMessagePacket | BulkMsgPacket;
+/**
+ * One `invitereq` fragment (PACKET_TYPE_INVITE_REQUEST = 34). Field layout per
+ * carrier/packet.fbs: 0=ext string, 1=tid long, 2=bundle string, 3=totalsz
+ * uint, 4=data [uint8]. Mirrors carrier_invite_friend's per-fragment packet.
+ */
+export type InviteReqPacket = {
+    type: typeof PACKET_TYPE_INVITE_REQUEST;
+    ext?: string;
+    tid: bigint;
+    bundle?: string;
+    /** Full data length — set on the FIRST fragment only, 0 on the rest. */
+    totalsz: number;
+    data: Uint8Array;
+};
+/**
+ * One `invitersp` fragment (PACKET_TYPE_INVITE_RESPONSE = 35). Field layout:
+ * 0=ext, 1=tid, 2=bundle, 3=totalsz, 4=status int, 5=reason string, 6=data.
+ * A non-zero status means "refused" (reason set, no data); status 0 means
+ * "confirmed" and carries data. The iOS WebRTC receiver never sends these
+ * (each RtcSignal is a one-way invitereq), but we decode them for completeness
+ * and can emit them if a peer does reply.
+ */
+export type InviteRspPacket = {
+    type: typeof PACKET_TYPE_INVITE_RESPONSE;
+    ext?: string;
+    tid: bigint;
+    bundle?: string;
+    totalsz: number;
+    status: number;
+    reason?: string;
+    data: Uint8Array;
+};
+export type CarrierPacket = UserInfoPacket | FriendRequestPacket | FriendMessagePacket | InviteReqPacket | InviteRspPacket | BulkMsgPacket;
 /**
  * Encode a Carrier `userinfo` packet (FB type 3). The Carrier C SDK sends
  * this every time the local user's name / status message / profile fields
@@ -75,4 +114,33 @@ export declare function encodeBulkMsgPacket(opts: {
     tid: bigint;
     data: Uint8Array;
 }): Uint8Array;
+/**
+ * Encode ONE `invitereq` fragment (PACKET_TYPE_INVITE_REQUEST = 34). Field
+ * layout per packet.fbs invitereq: 0=ext, 1=tid, 2=bundle, 3=totalsz, 4=data.
+ * Callers fragment the payload (INVITE_DATA_UNIT) and share one tid; only the
+ * first fragment sets totalsz (and the optional bundle). Mirrors the do/while
+ * in carrier_invite_friend.
+ */
+export declare function encodeInviteReqPacket(opts: {
+    ext?: string;
+    tid: bigint;
+    bundle?: string;
+    totalsz: number;
+    data: Uint8Array;
+}): Uint8Array;
+/**
+ * Encode ONE `invitersp` fragment (PACKET_TYPE_INVITE_RESPONSE = 35). Field
+ * layout: 0=ext, 1=tid, 2=bundle, 3=totalsz, 4=status, 5=reason, 6=data.
+ * status !== 0 → refused (reason set, no data); status === 0 → confirmed
+ * (carries data). Mirrors carrier_reply_friend_invite.
+ */
+export declare function encodeInviteRspPacket(opts: {
+    ext?: string;
+    tid: bigint;
+    bundle?: string;
+    totalsz: number;
+    status: number;
+    reason?: string;
+    data?: Uint8Array;
+}): Uint8Array;
 export declare function decodeCarrierPacket(bytes: Uint8Array): CarrierPacket;

package/dist/compat/packet.js

@@ -2,6 +2,8 @@ import { Builder, ByteBuffer, Encoding } from "flatbuffers";
 export const PACKET_TYPE_USERINFO = 3;
 export const PACKET_TYPE_FRIEND_REQUEST = 6;
 export const PACKET_TYPE_MESSAGE = 33;
+export const PACKET_TYPE_INVITE_REQUEST = 34;
+export const PACKET_TYPE_INVITE_RESPONSE = 35;
 export const PACKET_TYPE_BULKMSG = 36;
 // Carrier C SDK message-size constants (carrier.h). A single friendmsg may
 // carry at most 1024 bytes; anything larger is split into BULKMSG fragments
@@ -9,12 +11,29 @@ export const PACKET_TYPE_BULKMSG = 36;
 // only), reassembled in arrival order by the receiver.
 export const CARRIER_MAX_APP_MESSAGE_LEN = 1024;
 export const CARRIER_MAX_APP_BULKMSG_LEN = 5 * 1024 * 1024;
+// Carrier friend-invite constants (carrier.c / carrier.h). An invite carries
+// up to 8192 bytes of application data, fragmented into INVITE_DATA_UNIT-byte
+// chunks sharing one tid — the first fragment carries totalsz (and the
+// optional bundle), the rest carry totalsz=0. This is exactly the transport
+// the iOS/Android WebRTC SDK uses for call signaling (RtcSignal JSON), sent
+// via the "carrier" extension (CarrierExtension.sendInviteFriendRequest →
+// carrier_invite_friend(to="<userid>:carrier", bundle=NULL, ...)).
+export const INVITE_DATA_UNIT = 1280;
+export const CARRIER_MAX_INVITE_DATA_LEN = 8192;
+export const CARRIER_MAX_BUNDLE_LEN = 511;
+export const CARRIER_MAX_EXTENSION_NAME_LEN = 31;
+// The extension name the native SDK registers/sends under; the `ext` field of
+// every invitereq/invitersp on the wire. WebRTC signaling MUST use this so the
+// remote's registerExtension handler fires.
+export const CARRIER_EXTENSION_NAME = "carrier";
 // Body type indices into FlatBuffers `anybody` union (carrier/packet.fbs).
 // The .fbs declares: userinfo, friendreq, friendmsg, invitereq, invitersp,
 // bulkmsg — flatbuffers maps those to 1, 2, 3, 4, 5, 6 (NONE = 0).
 const ANYBODY_USERINFO = 1;
 const ANYBODY_FRIENDREQ = 2;
 const ANYBODY_FRIENDMSG = 3;
+const ANYBODY_INVITEREQ = 4;
+const ANYBODY_INVITERSP = 5;
 const ANYBODY_BULKMSG = 6;
 /**
  * Encode a Carrier `userinfo` packet (FB type 3). The Carrier C SDK sends
@@ -100,6 +119,73 @@ export function encodeBulkMsgPacket(opts) {
     const bulk = builder.endObject();
     return finishCarrierPacket(builder, PACKET_TYPE_BULKMSG, ANYBODY_BULKMSG, bulk);
 }
+/**
+ * Encode ONE `invitereq` fragment (PACKET_TYPE_INVITE_REQUEST = 34). Field
+ * layout per packet.fbs invitereq: 0=ext, 1=tid, 2=bundle, 3=totalsz, 4=data.
+ * Callers fragment the payload (INVITE_DATA_UNIT) and share one tid; only the
+ * first fragment sets totalsz (and the optional bundle). Mirrors the do/while
+ * in carrier_invite_friend.
+ */
+export function encodeInviteReqPacket(opts) {
+    const builder = new Builder(opts.data.length + 128);
+    const dataOffset = builder.createByteVector(opts.data);
+    const bundleOffset = opts.bundle ? builder.createString(opts.bundle) : 0;
+    const extOffset = opts.ext ? builder.createString(opts.ext) : 0;
+    builder.startObject(5);
+    builder.addFieldOffset(4, dataOffset, 0);
+    if (opts.totalsz) {
+        builder.addFieldInt32(3, opts.totalsz, 0);
+    }
+    if (bundleOffset) {
+        builder.addFieldOffset(2, bundleOffset, 0);
+    }
+    if (opts.tid !== 0n) {
+        builder.addFieldInt64(1, opts.tid, BigInt(0));
+    }
+    if (extOffset) {
+        builder.addFieldOffset(0, extOffset, 0);
+    }
+    const ireq = builder.endObject();
+    return finishCarrierPacket(builder, PACKET_TYPE_INVITE_REQUEST, ANYBODY_INVITEREQ, ireq);
+}
+/**
+ * Encode ONE `invitersp` fragment (PACKET_TYPE_INVITE_RESPONSE = 35). Field
+ * layout: 0=ext, 1=tid, 2=bundle, 3=totalsz, 4=status, 5=reason, 6=data.
+ * status !== 0 → refused (reason set, no data); status === 0 → confirmed
+ * (carries data). Mirrors carrier_reply_friend_invite.
+ */
+export function encodeInviteRspPacket(opts) {
+    const payload = opts.data ?? new Uint8Array();
+    const builder = new Builder(payload.length + 128);
+    const dataOffset = payload.length ? builder.createByteVector(payload) : 0;
+    const reasonOffset = opts.reason ? builder.createString(opts.reason) : 0;
+    const bundleOffset = opts.bundle ? builder.createString(opts.bundle) : 0;
+    const extOffset = opts.ext ? builder.createString(opts.ext) : 0;
+    builder.startObject(7);
+    if (dataOffset) {
+        builder.addFieldOffset(6, dataOffset, 0);
+    }
+    if (reasonOffset) {
+        builder.addFieldOffset(5, reasonOffset, 0);
+    }
+    if (opts.status) {
+        builder.addFieldInt32(4, opts.status, 0);
+    }
+    if (opts.totalsz) {
+        builder.addFieldInt32(3, opts.totalsz, 0);
+    }
+    if (bundleOffset) {
+        builder.addFieldOffset(2, bundleOffset, 0);
+    }
+    if (opts.tid !== 0n) {
+        builder.addFieldInt64(1, opts.tid, BigInt(0));
+    }
+    if (extOffset) {
+        builder.addFieldOffset(0, extOffset, 0);
+    }
+    const irsp = builder.endObject();
+    return finishCarrierPacket(builder, PACKET_TYPE_INVITE_RESPONSE, ANYBODY_INVITERSP, irsp);
+}
 export function decodeCarrierPacket(bytes) {
     const bb = new ByteBuffer(bytes);
     const root = bb.readInt32(bb.position()) + bb.position();
@@ -146,6 +232,28 @@ export function decodeCarrierPacket(bytes) {
             data: readByteVectorField(body, 3) ?? new Uint8Array()
         };
     }
+    if (type === PACKET_TYPE_INVITE_REQUEST && bodyType === ANYBODY_INVITEREQ) {
+        return {
+            type,
+            ext: readStringField(body, 0) ?? undefined,
+            tid: readInt64Field(body, 1),
+            bundle: readStringField(body, 2) ?? undefined,
+            totalsz: readUint32Field(body, 3),
+            data: readByteVectorField(body, 4) ?? new Uint8Array()
+        };
+    }
+    if (type === PACKET_TYPE_INVITE_RESPONSE && bodyType === ANYBODY_INVITERSP) {
+        return {
+            type,
+            ext: readStringField(body, 0) ?? undefined,
+            tid: readInt64Field(body, 1),
+            bundle: readStringField(body, 2) ?? undefined,
+            totalsz: readUint32Field(body, 3),
+            status: readInt32Field(body, 4),
+            reason: readStringField(body, 5) ?? undefined,
+            data: readByteVectorField(body, 6) ?? new Uint8Array()
+        };
+    }
     throw new Error(`unsupported carrier packet type/body: ${type}/${bodyType}`);
 }
 function finishCarrierPacket(builder, type, bodyType, bodyOffset) {
@@ -169,6 +277,10 @@ function readUint32Field(table, field) {
     const offset = table.bb.__offset(table.bb_pos, 4 + field * 2);
     return offset ? table.bb.readUint32(table.bb_pos + offset) : 0;
 }
+function readInt32Field(table, field) {
+    const offset = table.bb.__offset(table.bb_pos, 4 + field * 2);
+    return offset ? table.bb.readInt32(table.bb_pos + offset) : 0;
+}
 function readInt64Field(table, field) {
     const offset = table.bb.__offset(table.bb_pos, 4 + field * 2);
     return offset ? table.bb.readInt64(table.bb_pos + offset) : BigInt(0);

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 export { Peer } from "./peer.js";
 export { CARRIER_ADDRESS_SIZE, CARRIER_PUBLIC_KEY_SIZE, carrierAddressFromPublicKey, carrierIdFromAddress, carrierIdFromPublicKey, parseCarrierAddress } from "./compat/address.js";
-export { PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_MESSAGE, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket } from "./compat/packet.js";
+export { PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_MESSAGE, PACKET_TYPE_INVITE_REQUEST, PACKET_TYPE_INVITE_RESPONSE, INVITE_DATA_UNIT, CARRIER_MAX_INVITE_DATA_LEN, CARRIER_EXTENSION_NAME, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket, encodeInviteReqPacket, encodeInviteRspPacket } from "./compat/packet.js";
 export { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, CRYPTO_PACKET_NAT_PING, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 export { NET_PACKET_ONION_ANNOUNCE_REQUEST, NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_REQUEST, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID } from "./compat/tox-onion.js";
 export { signDetached, verifyDetached, SIGNATURE_LENGTH } from "./crypto/sign.js";
 export { base58ToBytes, bytesToBase58 } from "./utils/base58.js";
 export { LegacyProtocolNotImplementedError } from "./runtime/errors.js";
-export type { CarrierPacket, FriendMessagePacket, FriendRequestPacket } from "./compat/packet.js";
+export type { CarrierPacket, FriendMessagePacket, FriendRequestPacket, InviteReqPacket, InviteRspPacket } from "./compat/packet.js";
 export type { ToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 export type { CarrierAddressParts } from "./compat/address.js";
-export type { CompatibilityMode, CustomPacketEvent, FriendConnectionEvent, FriendConnectionStatus, FriendInfoEvent, FriendRequest, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
+export type { CompatibilityMode, CustomPacketEvent, FriendConnectionEvent, FriendConnectionStatus, FriendInfoEvent, FriendRequest, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 export { Peer } from "./peer.js";
 export { CARRIER_ADDRESS_SIZE, CARRIER_PUBLIC_KEY_SIZE, carrierAddressFromPublicKey, carrierIdFromAddress, carrierIdFromPublicKey, parseCarrierAddress } from "./compat/address.js";
-export { PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_MESSAGE, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket } from "./compat/packet.js";
+export { PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_MESSAGE, PACKET_TYPE_INVITE_REQUEST, PACKET_TYPE_INVITE_RESPONSE, INVITE_DATA_UNIT, CARRIER_MAX_INVITE_DATA_LEN, CARRIER_EXTENSION_NAME, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket, encodeInviteReqPacket, encodeInviteRspPacket } from "./compat/packet.js";
 export { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, CRYPTO_PACKET_NAT_PING, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 export { NET_PACKET_ONION_ANNOUNCE_REQUEST, NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_REQUEST, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID } from "./compat/tox-onion.js";
 export { signDetached, verifyDetached, SIGNATURE_LENGTH } from "./crypto/sign.js";

package/dist/peer.d.ts

@@ -1,6 +1,6 @@
 import { type BootstrapResult } from "./compat/bootstrap.js";
 import type { FriendRecord } from "./store/friends.js";
-import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
+import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
 export declare class Peer {
     #private;
     private constructor();
@@ -99,6 +99,34 @@ export declare class Peer {
         data: Uint8Array;
         fileType?: "image" | "audio" | "text" | "unknown";
     }): Promise<void>;
+    /** Fired when a peer sends a Carrier friend-invite (PACKET_TYPE_INVITE_REQUEST).
+     *  This is the channel the iOS/Android WebRTC SDK uses for call signaling —
+     *  each RtcSignal arrives as an "invite" with ext="carrier" and `data` the
+     *  reassembled JSON. */
+    onInvite(cb: (evt: InviteEvent) => void): void;
+    /** Fired when a peer replies to one of our invites (PACKET_TYPE_INVITE_RESPONSE).
+     *  Not used by the one-way WebRTC signaling flow, but surfaced for peers that
+     *  do reply. */
+    onInviteResponse(cb: (evt: InviteResponseEvent) => void): void;
+    /**
+     * Send a Carrier friend-invite to a peer — the transport the iOS/Android
+     * Elastos WebRTC SDK listens on (CarrierExtension.registerExtension). Used
+     * for realtime call signaling: pass the RtcSignal JSON as `data` and the
+     * remote's registerExtension handler fires with it.
+     *
+     * Wire-compatible with carrier_invite_friend: sends PACKET_TYPE_INVITE_REQUEST
+     * packets over the reliable message channel, `ext` = "carrier" by default,
+     * fragmented into INVITE_DATA_UNIT (1280-byte) chunks sharing one tid (first
+     * fragment carries totalsz + optional bundle). Signaling is realtime, so this
+     * requires a live session and does NOT fall back to offline express — a call
+     * signal to an unreachable peer should fail fast, not queue.
+     *
+     * @returns the tid used (lets callers correlate a later invite-response).
+     */
+    sendInvite(pubkey: string, data: Uint8Array | string, opts?: {
+        ext?: string | null;
+        bundle?: string;
+    }): Promise<bigint>;
     /**
      * Send an application-defined custom packet to a friend. `id` selects the
      * channel and its delivery class by toxcore range: **160–191 lossless**

package/dist/peer.js

@@ -5,7 +5,7 @@ import { dirname, join } from "node:path";
 import nacl from "tweetnacl";
 import { carrierAddressFromPublicKey, carrierIdFromAddress, carrierIdFromPublicKey, parseCarrierAddress } from "./compat/address.js";
 import { LegacyBootstrapClient } from "./compat/bootstrap.js";
-import { PACKET_TYPE_MESSAGE, PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_USERINFO, PACKET_TYPE_BULKMSG, CARRIER_MAX_APP_MESSAGE_LEN, CARRIER_MAX_APP_BULKMSG_LEN, encodeUserInfoPacket, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket, encodeBulkMsgPacket } from "./compat/packet.js";
+import { PACKET_TYPE_MESSAGE, PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_USERINFO, PACKET_TYPE_BULKMSG, PACKET_TYPE_INVITE_REQUEST, PACKET_TYPE_INVITE_RESPONSE, CARRIER_MAX_APP_MESSAGE_LEN, CARRIER_MAX_APP_BULKMSG_LEN, INVITE_DATA_UNIT, CARRIER_MAX_INVITE_DATA_LEN, CARRIER_EXTENSION_NAME, encodeUserInfoPacket, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket, encodeBulkMsgPacket, encodeInviteReqPacket } from "./compat/packet.js";
 import { NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID, createOnionAnnounceRequest, createOnionDataPacket, createOnionDataRequest, createOnionRequest0, openOnionAnnounceResponse, openOnionDataPacket, openOnionDataResponse } from "./compat/tox-onion.js";
 import { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 import { NET_PACKET_PING_REQUEST, NET_PACKET_PING_RESPONSE, NET_PACKET_GET_NODES, NET_PACKET_SEND_NODES, encodeDhtRpc, decodeDhtRpc, buildPingPlain, parsePingPlain, buildGetNodesPlain, parseGetNodesPlain, buildSendNodesPlain, parseSendNodesNodeBytes, packUdpNodeV4 } from "./compat/dht-rpc.js";
@@ -311,6 +311,10 @@ export class Peer {
     // them ordered) and the message completes when totalsz bytes arrived.
     // Mirrors the C SDK's bulkmsgs hashtable with its 60s assembly timeout.
     #bulkAssembly = new Map();
+    // Reassembly buffer for multi-fragment Carrier invites (WebRTC signaling).
+    // Keyed by `${friendId}:${tid}`; namespaced separately from #bulkAssembly so
+    // a bulkmsg and an invite that happen to share a tid can't collide.
+    #inviteAssembly = new Map();
     // When we FIRST deferred initiation to a higher-pubkey peer (per friend).
     // If the peer hasn't established within the grace window we break the
     // defer and initiate ourselves (see #initiateSession). Cleared whenever a
@@ -1125,6 +1129,81 @@ export class Peer {
         }
         await this.sendText(pubkey, envelope);
     }
+    /** Fired when a peer sends a Carrier friend-invite (PACKET_TYPE_INVITE_REQUEST).
+     *  This is the channel the iOS/Android WebRTC SDK uses for call signaling —
+     *  each RtcSignal arrives as an "invite" with ext="carrier" and `data` the
+     *  reassembled JSON. */
+    onInvite(cb) {
+        this.#events.on("invite", cb);
+    }
+    /** Fired when a peer replies to one of our invites (PACKET_TYPE_INVITE_RESPONSE).
+     *  Not used by the one-way WebRTC signaling flow, but surfaced for peers that
+     *  do reply. */
+    onInviteResponse(cb) {
+        this.#events.on("inviteResponse", cb);
+    }
+    /**
+     * Send a Carrier friend-invite to a peer — the transport the iOS/Android
+     * Elastos WebRTC SDK listens on (CarrierExtension.registerExtension). Used
+     * for realtime call signaling: pass the RtcSignal JSON as `data` and the
+     * remote's registerExtension handler fires with it.
+     *
+     * Wire-compatible with carrier_invite_friend: sends PACKET_TYPE_INVITE_REQUEST
+     * packets over the reliable message channel, `ext` = "carrier" by default,
+     * fragmented into INVITE_DATA_UNIT (1280-byte) chunks sharing one tid (first
+     * fragment carries totalsz + optional bundle). Signaling is realtime, so this
+     * requires a live session and does NOT fall back to offline express — a call
+     * signal to an unreachable peer should fail fast, not queue.
+     *
+     * @returns the tid used (lets callers correlate a later invite-response).
+     */
+    async sendInvite(pubkey, data, opts = {}) {
+        const friend = this.#friends.get(pubkey);
+        if (!friend) {
+            throw new Error(`Not a friend: ${pubkey}`);
+        }
+        const payload = typeof data === "string" ? new TextEncoder().encode(data) : data;
+        if (payload.length === 0 || payload.length > CARRIER_MAX_INVITE_DATA_LEN) {
+            throw new Error(`invite data must be 1..${CARRIER_MAX_INVITE_DATA_LEN} bytes (got ${payload.length})`);
+        }
+        // `ext: null` sends a plain invite (no extension); default is the "carrier"
+        // extension the native WebRTC SDK registers under.
+        const ext = opts.ext === null ? undefined : (opts.ext ?? CARRIER_EXTENSION_NAME);
+        const bundle = opts.bundle;
+        let session = this.#friendSessions.get(pubkey);
+        if (!session?.established) {
+            await this.#initiateSession(pubkey).catch(() => { });
+            const established = await this.#waitForFriendConnected(pubkey, 5000).catch(() => false);
+            if (established)
+                session = this.#friendSessions.get(pubkey);
+        }
+        if (!session?.established || !session.sessionSharedKey || !session.ourBaseNonce || !(session.remote || session.hasTcpRoute)) {
+            throw new Error(`cannot send invite: no live session to ${pubkey} (peer offline?)`);
+        }
+        // Fragment exactly like carrier_invite_friend: first fragment carries
+        // totalsz and the optional bundle (which counts against the first unit),
+        // the rest carry totalsz=0. bundle is usually absent for WebRTC.
+        const tid = (BigInt(Date.now()) << 20n) ^ BigInt(Math.floor(Math.random() * 0xfffff)) | 1n;
+        const bundleLen = bundle ? new TextEncoder().encode(bundle).length : 0;
+        let off = 0;
+        let first = true;
+        while (off < payload.length) {
+            const unit = first && bundle ? INVITE_DATA_UNIT - bundleLen : INVITE_DATA_UNIT;
+            const end = Math.min(off + unit, payload.length);
+            const p = encodeInviteReqPacket({
+                ext,
+                tid,
+                bundle: first ? bundle : undefined,
+                totalsz: first ? payload.length : 0,
+                data: payload.subarray(off, end)
+            });
+            await this.#sendMessengerPacket(pubkey, PACKET_ID_MESSAGE, p);
+            off = end;
+            first = false;
+        }
+        this.#debugLog(`invite sent to ${pubkey}: ext="${ext ?? ""}" (${payload.length} bytes, tid=${tid})`);
+        return tid;
+    }
     /**
      * Send an application-defined custom packet to a friend. `id` selects the
      * channel and its delivery class by toxcore range: **160–191 lossless**
@@ -2071,6 +2150,39 @@ export class Peer {
                         carrier = decodeCarrierPacket(inner);
                     }
                     catch { /* raw utf-8 peer */ }
+                    // Carrier friend-invite (PACKET_TYPE_INVITE_REQUEST/RESPONSE = 34/35)
+                    // rides this same PACKET_ID_MESSAGE channel — it's what the iOS/Android
+                    // WebRTC SDK uses for call signaling via the "carrier" extension. Large
+                    // signals (SDP offers) fragment by tid like bulkmsg; reassemble then
+                    // surface as an "invite" event (NOT chat text).
+                    if (carrier?.type === PACKET_TYPE_INVITE_REQUEST) {
+                        const complete = this.#assembleInvite(friendId, carrier);
+                        if (!complete)
+                            return; // more fragments pending
+                        this.#events.emit("invite", {
+                            pubkey: friendId,
+                            ext: carrier.ext,
+                            bundle: carrier.bundle,
+                            data: complete
+                        });
+                        this.#debugLog(`invite from ${friendId}: ext="${carrier.ext ?? ""}" (${complete.length} bytes)`);
+                        return;
+                    }
+                    if (carrier?.type === PACKET_TYPE_INVITE_RESPONSE) {
+                        const complete = carrier.status === 0 ? this.#assembleInvite(friendId, carrier) : new Uint8Array();
+                        if (carrier.status === 0 && !complete)
+                            return; // more fragments pending
+                        this.#events.emit("inviteResponse", {
+                            pubkey: friendId,
+                            ext: carrier.ext,
+                            bundle: carrier.bundle,
+                            status: carrier.status,
+                            reason: carrier.reason,
+                            data: complete ?? new Uint8Array()
+                        });
+                        this.#debugLog(`invite-response from ${friendId}: status=${carrier.status} ext="${carrier.ext ?? ""}"`);
+                        return;
+                    }
                     if (carrier?.type === PACKET_TYPE_BULKMSG) {
                         const complete = this.#assembleBulkMsg(friendId, carrier);
                         if (!complete)
@@ -2084,6 +2196,9 @@ export class Peer {
                     else {
                         text = decodeUtf8Best(inner);
                     }
+                    // Carrier C peers terminate strings with a NUL — strip it so chat
+                    // text doesn't carry an invisible trailing byte.
+                    text = text?.replace(/\0+$/u, "");
                     if (!text) {
                         this.#debugLog(`crypto message packet decode failed from ${friendId}`);
                         return;
@@ -3241,12 +3356,50 @@ export class Peer {
         this.#bulkAssembly.delete(key);
         return concatBytes(entry.chunks);
     }
+    /** Append a Carrier invite fragment (INVITE_REQUEST/RESPONSE); returns the
+     *  full reassembled payload when the last fragment lands, undefined while
+     *  pending. Mirrors #assembleBulkMsg but caps at CARRIER_MAX_INVITE_DATA_LEN
+     *  (8192) and uses a separate buffer. Single-fragment invites (the common
+     *  case for small WebRTC signals) complete on the first call. */
+    #assembleInvite(friendId, frag) {
+        const now = Date.now();
+        for (const [key, entry] of this.#inviteAssembly) {
+            if (entry.expireAtMs < now)
+                this.#inviteAssembly.delete(key);
+        }
+        const key = `${friendId}:${frag.tid.toString()}`;
+        let entry = this.#inviteAssembly.get(key);
+        if (!entry) {
+            // First fragment carries totalsz. A lone fragment whose data already
+            // equals totalsz completes immediately below.
+            if (!frag.totalsz || frag.totalsz > CARRIER_MAX_INVITE_DATA_LEN) {
+                this.#debugLog(`invite from ${friendId} with invalid/missing totalsz ${frag.totalsz} — dropped`);
+                return undefined;
+            }
+            entry = { total: frag.totalsz, chunks: [], got: 0, expireAtMs: now + 60_000 };
+            this.#inviteAssembly.set(key, entry);
+        }
+        if (frag.data.length === 0 || entry.got + frag.data.length > entry.total) {
+            this.#debugLog(`invite fragment from ${friendId} overflows totalsz — dropped`);
+            this.#inviteAssembly.delete(key);
+            return undefined;
+        }
+        entry.chunks.push(frag.data);
+        entry.got += frag.data.length;
+        if (entry.got < entry.total)
+            return undefined;
+        this.#inviteAssembly.delete(key);
+        return concatBytes(entry.chunks);
+    }
     /** iOS Beagle sends files inline as a JSON envelope over (bulk)messages:
      *  {"data":"<base64>","fileExtension":".jpg","fileName":"…","type":"image"}.
      *  Detect it, decode, and emit an inlineFile event instead of dumping
      *  base64 into the chat. Returns true when handled. */
     #tryEmitInlineFile(friendId, text, via) {
-        const trimmed = text.trimStart();
+        // The Carrier C SDK sends messages with a trailing C-string NUL, which
+        // JSON.parse rejects. iOS's own decoder strips NULs before parsing
+        // (CodableUtil.decode: replacingOccurrences(of: "\0")) — mirror that.
+        const trimmed = text.replaceAll("\0", "").trim();
         if (!trimmed.startsWith("{") || !trimmed.includes("\"fileName\"") || !trimmed.includes("\"data\"")) {
             return false;
         }

package/dist/types/peer.d.ts

@@ -130,6 +130,35 @@ export type InlineFileEvent = {
     data: Uint8Array;
     via: "online" | "offline";
 };
+/**
+ * A Carrier friend-invite request received from a peer (PACKET_TYPE_INVITE_REQUEST).
+ * This is the transport the iOS/Android Elastos WebRTC SDK uses for call
+ * signaling: each RtcSignal (offer/answer/candidate/bye JSON) is sent as a
+ * one-way invite under the "carrier" extension. `data` is the reassembled
+ * application payload (JSON for WebRTC; NUL-terminated by native C senders).
+ */
+export type InviteEvent = {
+    pubkey: string;
+    /** Extension name — "carrier" for WebRTC/extension invites, undefined for a plain invite. */
+    ext?: string;
+    /** Optional bundle string set by the sender (usually absent). */
+    bundle?: string;
+    data: Uint8Array;
+};
+/**
+ * A Carrier friend-invite response (PACKET_TYPE_INVITE_RESPONSE). The iOS
+ * WebRTC receiver never sends these (signaling is one-way invitereq both
+ * ways), but a peer that calls reply_friend_invite produces one. status 0 =
+ * confirmed (carries data); non-zero = refused (reason set, no data).
+ */
+export type InviteResponseEvent = {
+    pubkey: string;
+    ext?: string;
+    bundle?: string;
+    status: number;
+    reason?: string;
+    data: Uint8Array;
+};
 export type LookupResult = {
     pubkey: string;
     status: "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.82",
+  "version": "0.1.84",
   "description": "Pure TypeScript port of Elastos Carrier (toxcore-derived) P2P messaging. DHT, onion routing, TCP relay, FlatBuffers app payloads, Express offline relay. Wire-compatible with iOS Beagle and the Carrier C SDK.",
   "type": "module",
   "main": "./dist/index.js",
@@ -67,6 +67,7 @@
     "demo:js-to-js": "pnpm run build && node scripts/js-to-js-demo.mjs",
     "demo:tox-dht-crypto": "pnpm run build && node scripts/tox-dht-crypto-demo.mjs",
     "test:compat": "pnpm run build && node scripts/compat-selftest.mjs",
+    "test:invite": "pnpm run build && node scripts/invite-selftest.mjs",
     "smoke:join": "node scripts/smoke-join.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:express": "pnpm run build && node scripts/express-scheme-selftest.mjs"