signal-sdk 0.0.9 → 0.1.1

package/dist/SignalCli.d.ts

@@ -1,12 +1,23 @@
-import { Message, Contact, GroupUpdateOptions, SendMessageOptions, ContactUpdateOptions, AccountConfiguration, Device, ReceiptType, StickerPack, IdentityKey, LinkingOptions, LinkingResult, MessageRequestResponseType, SendResponse, GroupInfo, RemoveContactOptions, UserStatusResult, PaymentNotificationData, StickerPackManifest, StickerPackUploadResult, RateLimitChallengeResult, ChangeNumberSession, UploadProgress } 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 } from './interfaces';
 import { EventEmitter } from 'events';
+import { SignalCliConfig } from './config';
 export declare class SignalCli extends EventEmitter {
     private signalCliPath;
     private account?;
     private cliProcess;
     private requestPromises;
-    constructor(accountOrPath?: string, account?: string);
+    private config;
+    private logger;
+    private rateLimiter;
+    private reconnectAttempts;
+    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;
@@ -36,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.
@@ -57,6 +117,45 @@ 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[]>;
     listAccounts(): Promise<string[]>;
@@ -75,6 +174,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
@@ -89,10 +215,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>;
     /**
@@ -109,19 +247,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
@@ -132,4 +278,157 @@ export declare class SignalCli extends EventEmitter {
     sendMessageWithProgress(recipient: string, message: string, options?: SendMessageOptions & {
         onProgress?: (progress: UploadProgress) => void;
     }): Promise<SendResponse>;
+    /**
+     * Send a poll create message to a recipient or group.
+     * @param options Poll creation options
+     * @returns Send response with timestamp
+     */
+    sendPollCreate(options: PollCreateOptions): Promise<SendResponse>;
+    /**
+     * Send a poll vote message to vote on a poll.
+     * @param recipient Recipient or group ID
+     * @param options Poll vote options
+     * @returns Send response with timestamp
+     */
+    sendPollVote(recipient: string, options: PollVoteOptions): Promise<SendResponse>;
+    /**
+     * Send a poll terminate message to close a poll.
+     * @param recipient Recipient or group ID
+     * @param options Poll terminate options
+     * @returns Send response with timestamp
+     */
+    sendPollTerminate(recipient: string, options: PollTerminateOptions): Promise<SendResponse>;
+    /**
+     * Update account information (device name, username, privacy settings).
+     * @param options Account update options
+     * @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
+     * @returns Base64 encoded attachment data
+     */
+    getAttachment(options: GetAttachmentOptions): Promise<string>;
+    /**
+     * Get raw avatar data as base64 string.
+     * @param options Avatar retrieval options
+     * @returns Base64 encoded avatar data
+     */
+    getAvatar(options: GetAvatarOptions): Promise<string>;
+    /**
+     * Get raw sticker data as base64 string.
+     * @param options Sticker retrieval options
+     * @returns Base64 encoded sticker data
+     */
+    getSticker(options: GetStickerOptions): Promise<string>;
+    /**
+     * Send contacts synchronization message to linked devices.
+     * @param options Contacts sync options
+     */
+    sendContacts(options?: SendContactsOptions): Promise<void>;
+    /**
+     * List groups with optional filtering and details.
+     * @param options List groups options
+     * @returns Array of group information
+     */
+    listGroupsDetailed(options?: ListGroupsOptions): Promise<GroupInfo[]>;
+    /**
+     * List all local accounts.
+     * @returns Array of account phone numbers
+     */
+    listAccountsDetailed(): Promise<Array<{
+        number: string;
+        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[]>;
 }