@zapyapi/sdk 1.0.0-beta.1

package/src/types/webhook-events.types.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Webhook event type definitions
+ * Types for webhook payloads sent by ZapyAPI
+ */
+import type { MessageType, MessageAckStatus, ConnectionStatus, WebhookEventType as WebhookEventTypeEnum } from './enums';
+/**
+ * Re-export the enum type for convenience
+ */
+export type WebhookEventType = WebhookEventTypeEnum;
+/**
+ * Base webhook event payload
+ * All webhook events include these fields
+ */
+export interface WebhookEventBase<T extends WebhookEventType = WebhookEventType> {
+    /** Event type identifier */
+    event: T;
+    /** Instance ID that generated the event */
+    instanceId: string;
+}
+/**
+ * Message sender/recipient info
+ */
+export interface MessageParticipant {
+    /** WhatsApp ID (e.g., "5511999999999@c.us") */
+    id: string;
+    /** Phone number (e.g., "5511999999999") */
+    phone: string;
+    /** Display name if available */
+    name?: string;
+    /** Push name (user's WhatsApp name) */
+    pushName?: string;
+}
+/**
+ * Media information in messages
+ */
+export interface MediaInfo {
+    /** MIME type of the media */
+    mimeType: string;
+    /** File name if available */
+    fileName?: string;
+    /** File size in bytes */
+    fileSize?: number;
+    /** Media URL (temporary, expires) */
+    url?: string;
+}
+/**
+ * Message webhook event data
+ */
+export interface MessageEventData {
+    /** WhatsApp message ID */
+    messageId: string;
+    /** Message sender */
+    from: MessageParticipant;
+    /** Message recipient (your number/instance) */
+    to: MessageParticipant;
+    /** Message content type */
+    type: MessageType;
+    /** Text content (for text messages) */
+    text?: string;
+    /** Caption (for media messages) */
+    caption?: string;
+    /** Media information (for media messages) */
+    media?: MediaInfo;
+    /** Whether this is a group message */
+    isGroup: boolean;
+    /** Group participant who sent the message (for group messages) */
+    participant?: MessageParticipant;
+    /** ID of quoted/replied message */
+    quotedMessageId?: string;
+    /** Message timestamp (Unix ms) */
+    timestamp: number;
+    /** Whether this is a forwarded message */
+    isForwarded?: boolean;
+    /** Whether this is a broadcast message */
+    isBroadcast?: boolean;
+}
+/**
+ * Message webhook event
+ */
+export interface MessageWebhookEvent extends WebhookEventBase<'message'> {
+    data: MessageEventData;
+}
+/**
+ * Message status update event data
+ */
+export interface MessageStatusEventData {
+    /** WhatsApp message ID */
+    messageId: string;
+    /** New acknowledgment status */
+    ack: MessageAckStatus;
+    /** Sender of the original message */
+    from: string;
+    /** Recipient of the original message */
+    to: string;
+    /** Timestamp of status update (Unix ms) */
+    timestamp: number;
+}
+/**
+ * Message acknowledgment/status webhook event
+ */
+export interface MessageAckWebhookEvent extends WebhookEventBase<'message-status'> {
+    data: MessageStatusEventData;
+}
+/**
+ * QR code update event data
+ */
+export interface QRCodeEventData {
+    /** QR code as base64 data URL */
+    qrCode: string;
+    /** QR code generation attempt number */
+    attempt: number;
+    /** Expiration timestamp (Unix ms) */
+    expiresAt: number;
+}
+/**
+ * QR code update webhook event
+ */
+export interface QRCodeWebhookEvent extends WebhookEventBase<'qr-code'> {
+    data: QRCodeEventData;
+}
+/**
+ * Contact information
+ */
+export interface ContactInfo {
+    /** WhatsApp ID */
+    id: string;
+    /** Phone number */
+    phone: string;
+    /** Contact name */
+    name?: string;
+    /** Push name (WhatsApp display name) */
+    pushName?: string;
+    /** Profile picture URL */
+    profilePicUrl?: string;
+    /** Whether this is a business account */
+    isBusiness?: boolean;
+}
+/**
+ * Contact created event data
+ */
+export interface ContactCreatedEventData {
+    /** The new contact */
+    contact: ContactInfo;
+}
+/**
+ * Contact created webhook event
+ */
+export interface ContactCreatedWebhookEvent extends WebhookEventBase<'contact-created'> {
+    data: ContactCreatedEventData;
+}
+/**
+ * Contact updated event data
+ */
+export interface ContactUpdatedEventData {
+    /** The updated contact */
+    contact: ContactInfo;
+    /** Fields that were updated */
+    updatedFields: string[];
+}
+/**
+ * Contact updated webhook event
+ */
+export interface ContactUpdatedWebhookEvent extends WebhookEventBase<'contact-updated'> {
+    data: ContactUpdatedEventData;
+}
+/**
+ * Contact deduplicated event data
+ */
+export interface ContactDeduplicatedEventData {
+    /** The primary contact that was kept */
+    primaryContact: ContactInfo;
+    /** The duplicate contact that was merged */
+    duplicateContact: ContactInfo;
+}
+/**
+ * Contact deduplicated webhook event
+ */
+export interface ContactDeduplicatedWebhookEvent extends WebhookEventBase<'contact-deduplicated'> {
+    data: ContactDeduplicatedEventData;
+}
+/**
+ * Connection status update event data
+ * @deprecated Connection events are now sent as instance status changes
+ */
+export interface ConnectionEventData {
+    /** Connection status */
+    status: ConnectionStatus;
+    /** Reason for status change */
+    reason?: string;
+}
+/**
+ * Connection status webhook event
+ * @deprecated Connection events are now sent as instance status changes
+ */
+export interface ConnectionWebhookEvent {
+    event: 'connection.update';
+    instanceId: string;
+    data: ConnectionEventData;
+}
+/**
+ * Union type for all webhook events
+ *
+ * @example
+ * ```typescript
+ * import { WebhookEvent, WebhookEventType } from '@zapyapi/sdk';
+ *
+ * function handleWebhook(event: WebhookEvent) {
+ *   switch (event.event) {
+ *     case 'message':
+ *       console.log('New message:', event.data.text);
+ *       break;
+ *     case 'message-status':
+ *       console.log('Status update:', event.data.ack);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type WebhookEvent = MessageWebhookEvent | MessageAckWebhookEvent | QRCodeWebhookEvent | ContactCreatedWebhookEvent | ContactUpdatedWebhookEvent | ContactDeduplicatedWebhookEvent;
+/** Type guard for message events */
+export declare function isMessageEvent(event: WebhookEvent): event is MessageWebhookEvent;
+/** Type guard for message status events */
+export declare function isMessageStatusEvent(event: WebhookEvent): event is MessageAckWebhookEvent;
+/** Type guard for QR code events */
+export declare function isQRCodeEvent(event: WebhookEvent): event is QRCodeWebhookEvent;
+/** Type guard for contact created events */
+export declare function isContactCreatedEvent(event: WebhookEvent): event is ContactCreatedWebhookEvent;
+/** Type guard for contact updated events */
+export declare function isContactUpdatedEvent(event: WebhookEvent): event is ContactUpdatedWebhookEvent;
+/** Type guard for contact deduplicated events */
+export declare function isContactDeduplicatedEvent(event: WebhookEvent): event is ContactDeduplicatedWebhookEvent;
+//# sourceMappingURL=webhook-events.types.d.ts.map

package/src/types/webhook-events.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-events.types.d.ts","sourceRoot":"","sources":["../../../../../libs/sdk/src/types/webhook-events.types.ts"],"names":[],"mappings":"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"}

package/src/utils/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Utility exports for @zapyapi/sdk
+ */
+export { normalizePhone, isValidPhone, isGroup, extractPhone } from './phone';
+export { verifyWebhookSignature, verifyWebhookSignatureAsync } from './webhook-signature';
+//# sourceMappingURL=index.d.ts.map

package/src/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../libs/sdk/src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC"}

package/src/utils/phone.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Phone number utilities for @zapyapi/sdk
+ */
+/**
+ * Normalize a phone number to the format expected by the API
+ *
+ * @param phone - Phone number in various formats
+ * @returns Normalized phone number
+ *
+ * @example
+ * normalizePhone('11999999999')     // '5511999999999'
+ * normalizePhone('5511999999999')   // '5511999999999'
+ * normalizePhone('+5511999999999')  // '5511999999999'
+ * normalizePhone('5511999999999@c.us') // '5511999999999@c.us'
+ */
+export declare function normalizePhone(phone: string): string;
+/**
+ * Validate if a string is a valid phone number format
+ *
+ * @param phone - Phone number to validate
+ * @returns Whether the phone number is valid
+ */
+export declare function isValidPhone(phone: string): boolean;
+/**
+ * Check if a WhatsApp ID is a group
+ *
+ * @param jid - WhatsApp ID (JID)
+ * @returns Whether the JID is a group
+ */
+export declare function isGroup(jid: string): boolean;
+/**
+ * Extract the phone number from a WhatsApp ID
+ *
+ * @param jid - WhatsApp ID (JID)
+ * @returns Phone number without the @suffix
+ */
+export declare function extractPhone(jid: string): string;
+//# sourceMappingURL=phone.d.ts.map

package/src/utils/phone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phone.d.ts","sourceRoot":"","sources":["../../../../../libs/sdk/src/utils/phone.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqBpD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAYnD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhD"}

package/src/utils/webhook-signature.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Webhook signature verification utilities
+ * HMAC-SHA256 signature verification for webhook payloads
+ */
+/**
+ * Verify webhook signature (synchronous)
+ *
+ * For best results, pass the raw request body as a string.
+ *
+ * @param payload - The webhook payload (raw body string recommended)
+ * @param signature - The X-Webhook-Signature header value
+ * @param secret - Your webhook secret
+ * @returns true if the signature is valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@zapyapi/sdk';
+ *
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'] as string;
+ *   const isValid = verifyWebhookSignature(
+ *     req.body.toString('utf8'),
+ *     signature,
+ *     process.env.WEBHOOK_SECRET!
+ *   );
+ *
+ *   if (!isValid) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = JSON.parse(req.body.toString('utf8'));
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+export declare function verifyWebhookSignature(payload: string | object, signature: string | undefined, secret: string): boolean;
+/**
+ * Verify webhook signature (async - recommended for ESM)
+ *
+ * Uses dynamic import() for ESM compatibility.
+ *
+ * @param payload - The webhook payload (raw body string recommended)
+ * @param signature - The X-Webhook-Signature header value
+ * @param secret - Your webhook secret
+ * @returns Promise resolving to true if valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignatureAsync } from '@zapyapi/sdk';
+ *
+ * app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'] as string;
+ *   const isValid = await verifyWebhookSignatureAsync(
+ *     req.body.toString('utf8'),
+ *     signature,
+ *     process.env.WEBHOOK_SECRET!
+ *   );
+ *
+ *   if (!isValid) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = JSON.parse(req.body.toString('utf8'));
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+export declare function verifyWebhookSignatureAsync(payload: string | object, signature: string | undefined, secret: string): Promise<boolean>;
+//# sourceMappingURL=webhook-signature.d.ts.map

package/src/utils/webhook-signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-signature.d.ts","sourceRoot":"","sources":["../../../../../libs/sdk/src/utils/webhook-signature.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,GACb,OAAO,CAgBT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,CAelB"}

package/src/version.d.ts

@@ -0,0 +1,3 @@
+/** SDK version - auto-generated from package.json */
+export declare const SDK_VERSION = "1.0.0-beta.1";
+//# sourceMappingURL=version.d.ts.map

package/src/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../../libs/sdk/src/version.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,eAAO,MAAM,WAAW,iBAAiB,CAAC"}