signal-sdk 0.1.0 → 0.1.2

package/dist/SignalCli.d.ts

@@ -1,4 +1,4 @@
-import { Message, Contact, GroupUpdateOptions, SendMessageOptions, ContactUpdateOptions, AccountConfiguration, Device, ReceiptType, StickerPack, IdentityKey, LinkingOptions, LinkingResult, MessageRequestResponseType, SendResponse, GroupInfo, RemoveContactOptions, UserStatusResult, PaymentNotificationData, StickerPackManifest, StickerPackUploadResult, RateLimitChallengeResult, ChangeNumberSession, UploadProgress, PollCreateOptions, PollVoteOptions, PollTerminateOptions, GetAttachmentOptions, GetAvatarOptions, GetStickerOptions, UpdateAccountOptions, AccountUpdateResult, SendContactsOptions, ListGroupsOptions } from './interfaces';
+import { Message, Contact, GroupUpdateOptions, SendMessageOptions, ContactUpdateOptions, AccountConfiguration, Device, ReceiptType, StickerPack, IdentityKey, LinkingOptions, LinkingResult, MessageRequestResponseType, SendResponse, GroupInfo, RemoveContactOptions, UserStatusResult, PaymentNotificationData, StickerPackManifest, StickerPackUploadResult, RateLimitChallengeResult, ReceiveOptions, UploadProgress, PollCreateOptions, PollVoteOptions, PollTerminateOptions, GetAttachmentOptions, GetAvatarOptions, GetStickerOptions, UpdateAccountOptions, AccountUpdateResult, SendContactsOptions, ListGroupsOptions, UpdateDeviceOptions } from './interfaces';
 import { EventEmitter } from 'events';
 import { SignalCliConfig } from './config';
 export declare class SignalCli extends EventEmitter {
@@ -13,6 +13,11 @@ export declare class SignalCli extends EventEmitter {
     private maxReconnectAttempts;
     constructor(accountOrPath?: string, account?: string, config?: SignalCliConfig);
     connect(): Promise<void>;
+    private connectJsonRpc;
+    private connectUnixSocket;
+    private connectTcp;
+    private connectHttp;
+    private httpRequest;
     disconnect(): void;
     gracefulShutdown(): Promise<void>;
     private handleRpcResponse;
@@ -42,6 +47,55 @@ export declare class SignalCli extends EventEmitter {
     removePin(): Promise<void>;
     listIdentities(number?: string): Promise<IdentityKey[]>;
     trustIdentity(number: string, safetyNumber: string, verified?: boolean): Promise<void>;
+    /**
+     * Get the safety number for a specific contact.
+     * This is a helper method that extracts just the safety number from identity information.
+     *
+     * @param number - The phone number of the contact
+     * @returns The safety number string, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const safetyNumber = await signal.getSafetyNumber('+33123456789');
+     * console.log(`Safety number: ${safetyNumber}`);
+     * ```
+     */
+    getSafetyNumber(number: string): Promise<string | null>;
+    /**
+     * Verify a safety number for a contact.
+     * Checks if the provided safety number matches the stored one and marks it as trusted if it does.
+     *
+     * @param number - The phone number of the contact
+     * @param safetyNumber - The safety number to verify
+     * @returns True if the safety number matches and was trusted, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const verified = await signal.verifySafetyNumber('+33123456789', '123456 78901...');
+     * if (verified) {
+     *   console.log('Safety number verified and trusted');
+     * } else {
+     *   console.log('Safety number does not match!');
+     * }
+     * ```
+     */
+    verifySafetyNumber(number: string, safetyNumber: string): Promise<boolean>;
+    /**
+     * List all untrusted identities.
+     * Returns identities that have not been explicitly trusted.
+     *
+     * @returns Array of untrusted identity keys
+     *
+     * @example
+     * ```typescript
+     * const untrusted = await signal.listUntrustedIdentities();
+     * console.log(`Found ${untrusted.length} untrusted identities`);
+     * untrusted.forEach(id => {
+     *   console.log(`${id.number}: ${id.safetyNumber}`);
+     * });
+     * ```
+     */
+    listUntrustedIdentities(): Promise<IdentityKey[]>;
     link(deviceName?: string): Promise<string>;
     /**
      * Link a new device to an existing Signal account with QR code support.
@@ -63,8 +117,67 @@ export declare class SignalCli extends EventEmitter {
     createGroup(name: string, members: string[]): Promise<GroupInfo>;
     updateGroup(groupId: string, options: GroupUpdateOptions): Promise<void>;
     listGroups(): Promise<GroupInfo[]>;
+    /**
+     * Send group invite link to a recipient.
+     * Retrieves and sends the invitation link for a group.
+     *
+     * @param groupId - The group ID
+     * @param recipient - The recipient to send the invite link to
+     * @returns Send response
+     *
+     * @example
+     * ```typescript
+     * await signal.sendGroupInviteLink('groupId123==', '+33123456789');
+     * ```
+     */
+    sendGroupInviteLink(groupId: string, recipient: string): Promise<SendResponse>;
+    /**
+     * Set banned members for a group.
+     * Ban specific members from the group.
+     *
+     * @param groupId - The group ID
+     * @param members - Array of phone numbers to ban
+     *
+     * @example
+     * ```typescript
+     * await signal.setBannedMembers('groupId123==', ['+33111111111', '+33222222222']);
+     * ```
+     */
+    setBannedMembers(groupId: string, members: string[]): Promise<void>;
+    /**
+     * Reset group invite link.
+     * Invalidates the current group invite link and generates a new one.
+     *
+     * @param groupId - The group ID
+     *
+     * @example
+     * ```typescript
+     * await signal.resetGroupLink('groupId123==');
+     * ```
+     */
+    resetGroupLink(groupId: string): Promise<void>;
     listContacts(): Promise<Contact[]>;
     listDevices(): Promise<Device[]>;
+    /**
+     * Update a linked device name (signal-cli v0.13.23+).
+     * Allows changing the display name of a linked device.
+     *
+     * @param options - Device update options
+     * @returns Promise that resolves when device is updated
+     *
+     * @example
+     * ```typescript
+     * // List devices to get device IDs
+     * const devices = await signal.listDevices();
+     *
+     * // Update device name
+     * await signal.updateDevice({
+     *   deviceId: 2,
+     *   deviceName: 'My New Device Name'
+     * });
+     * ```
+     */
+    updateDevice(options: UpdateDeviceOptions): Promise<void>;
     listAccounts(): Promise<string[]>;
     /**
      * @deprecated Use `connect` and listen for `message` events instead.
@@ -81,6 +194,33 @@ export declare class SignalCli extends EventEmitter {
      * This method now calls gracefulShutdown() for backward compatibility.
      */
     stopDaemon(): void;
+    /**
+     * Receive messages from Signal with configurable options.
+     * This is the modern replacement for the deprecated receiveMessages().
+     *
+     * @param options - Options for receiving messages
+     * @returns Array of received messages
+     *
+     * @example
+     * ```typescript
+     * // Receive with default timeout
+     * const messages = await signal.receive();
+     *
+     * // Receive with custom options
+     * const messages = await signal.receive({
+     *   timeout: 10,
+     *   maxMessages: 5,
+     *   ignoreAttachments: true,
+     *   sendReadReceipts: true
+     * });
+     * ```
+     */
+    receive(options?: ReceiveOptions): Promise<Message[]>;
+    /**
+     * Parse a message envelope from signal-cli into a Message object.
+     * @private
+     */
+    private parseEnvelope;
     /**
      * Remove a contact from the contact list.
      * @param number - The phone number of the contact to remove
@@ -95,10 +235,22 @@ export declare class SignalCli extends EventEmitter {
      */
     getUserStatus(numbers?: string[], usernames?: string[]): Promise<UserStatusResult[]>;
     /**
-     * Send a payment notification to a recipient.
-     * @param recipient - Phone number or group ID to send the notification to
-     * @param paymentData - Payment notification data including receipt
-     * @returns Send response with timestamp and other details
+     * Send a payment notification to a recipient (MobileCoin).
+     * Sends a notification about a cryptocurrency payment made through Signal's MobileCoin integration.
+     *
+     * @param recipient - The phone number or group ID of the recipient
+     * @param paymentData - Payment notification data including receipt and optional note
+     * @returns Send result with timestamp
+     * @throws {Error} If receipt is invalid or sending fails
+     *
+     * @example
+     * ```typescript
+     * const receiptBlob = 'base64EncodedReceiptData...';
+     * await signal.sendPaymentNotification('+33612345678', {
+     *   receipt: receiptBlob,
+     *   note: 'Thanks for dinner!'
+     * });
+     * ```
      */
     sendPaymentNotification(recipient: string, paymentData: PaymentNotificationData): Promise<SendResponse>;
     /**
@@ -115,19 +267,27 @@ export declare class SignalCli extends EventEmitter {
      */
     submitRateLimitChallenge(challenge: string, captcha: string): Promise<RateLimitChallengeResult>;
     /**
-     * Start the process of changing phone number.
-     * @param newNumber - The new phone number to change to
-     * @param voice - Whether to use voice verification instead of SMS
-     * @param captcha - Captcha token if required
-     * @returns Change number session information
+     * Start the phone number change process.
+     * Initiates SMS or voice verification for changing your account to a new phone number.
+     * After calling this, you must verify the new number with finishChangeNumber().
+     *
+     * @param newNumber - The new phone number in E164 format (e.g., "+33612345678")
+     * @param voice - Use voice verification instead of SMS (default: false)
+     * @param captcha - Optional captcha token if required
+     * @throws {Error} If not a primary device or rate limited
      */
-    startChangeNumber(newNumber: string, voice?: boolean, captcha?: string): Promise<ChangeNumberSession>;
+    startChangeNumber(newNumber: string, voice?: boolean, captcha?: string): Promise<void>;
     /**
-     * Finish the phone number change process with verification code.
-     * @param verificationCode - The verification code received via SMS/voice
-     * @param pin - Registration lock PIN if enabled
+     * Complete the phone number change process.
+     * Verifies the code received via SMS or voice and changes your account to the new number.
+     * Must be called after startChangeNumber().
+     *
+     * @param newNumber - The new phone number (same as startChangeNumber)
+     * @param verificationCode - The verification code received via SMS or voice
+     * @param pin - Optional registration lock PIN if one was set
+     * @throws {Error} If verification fails or incorrect PIN
      */
-    finishChangeNumber(verificationCode: string, pin?: string): Promise<void>;
+    finishChangeNumber(newNumber: string, verificationCode: string, pin?: string): Promise<void>;
     /**
      * Enhanced send message with progress callback support.
      * @param recipient - Phone number or group ID
@@ -164,6 +324,36 @@ export declare class SignalCli extends EventEmitter {
      * @returns Account update result
      */
     updateAccount(options: UpdateAccountOptions): Promise<AccountUpdateResult>;
+    /**
+     * Set or update the username for this account.
+     * Helper method that wraps updateAccount() for simpler username management.
+     *
+     * @param username - The username to set (without discriminator)
+     * @returns Account update result with username and link
+     *
+     * @example
+     * ```typescript
+     * const result = await signal.setUsername('myusername');
+     * console.log(`Username: ${result.username}`);
+     * console.log(`Link: ${result.usernameLink}`);
+     * ```
+     */
+    setUsername(username: string): Promise<AccountUpdateResult>;
+    /**
+     * Delete the current username from this account.
+     * Helper method that wraps updateAccount() for simpler username deletion.
+     *
+     * @returns Account update result
+     *
+     * @example
+     * ```typescript
+     * const result = await signal.deleteUsername();
+     * if (result.success) {
+     *   console.log('Username deleted successfully');
+     * }
+     * ```
+     */
+    deleteUsername(): Promise<AccountUpdateResult>;
     /**
      * Get raw attachment data as base64 string.
      * @param options Attachment retrieval options
@@ -202,4 +392,63 @@ export declare class SignalCli extends EventEmitter {
         name?: string;
         uuid?: string;
     }>>;
+    /**
+     * Extract profile information from a contact.
+     * Parses givenName, familyName, mobileCoinAddress from profile data.
+     *
+     * @param contact - The contact object to parse
+     * @returns Enhanced contact with extracted profile fields
+     *
+     * @example
+     * ```typescript
+     * const contacts = await signal.listContacts();
+     * const enriched = signal.parseContactProfile(contacts[0]);
+     * console.log(enriched.givenName, enriched.familyName);
+     * ```
+     */
+    parseContactProfile(contact: Contact): Contact;
+    /**
+     * Extract group membership details.
+     * Parses pendingMembers, bannedMembers, inviteLink from group data.
+     *
+     * @param group - The group info to parse
+     * @returns Enhanced group with extracted membership fields
+     *
+     * @example
+     * ```typescript
+     * const groups = await signal.listGroups();
+     * const enriched = signal.parseGroupDetails(groups[0]);
+     * console.log(enriched.pendingMembers, enriched.bannedMembers);
+     * ```
+     */
+    parseGroupDetails(group: GroupInfo): GroupInfo;
+    /**
+     * Get enriched contacts list with parsed profile information.
+     *
+     * @returns Array of contacts with full profile data
+     *
+     * @example
+     * ```typescript
+     * const contacts = await signal.getContactsWithProfiles();
+     * contacts.forEach(c => {
+     *   console.log(`${c.givenName} ${c.familyName} - ${c.mobileCoinAddress}`);
+     * });
+     * ```
+     */
+    getContactsWithProfiles(): Promise<Contact[]>;
+    /**
+     * Get enriched groups list with parsed membership details.
+     *
+     * @param options - List groups options
+     * @returns Array of groups with full membership data
+     *
+     * @example
+     * ```typescript
+     * const groups = await signal.getGroupsWithDetails();
+     * groups.forEach(g => {
+     *   console.log(`${g.name}: ${g.members.length} members, ${g.pendingMembers.length} pending`);
+     * });
+     * ```
+     */
+    getGroupsWithDetails(options?: ListGroupsOptions): Promise<GroupInfo[]>;
 }