@wesell/n8n-nodes-confirmx 0.1.0

package/transports/signature.ts

@@ -0,0 +1,55 @@
+/**
+ * HMAC-SHA256 signature verification for inbound ConfirmX webhooks.
+ *
+ * Must stay byte-compatible with the verifier in
+ * apps/worker/src/lib/webhooks.ts::verifyPayload (and the corresponding
+ * outbound signer in apps/api/src/lib/webhooks.ts::signPayload). The
+ * signing scheme is `${timestamp}.${body}` keyed by the per-webhook
+ * plaintext secret; the receiver must also enforce a 300s skew window
+ * to defeat replay.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+export interface VerifyOpts {
+  secret: string
+  body: string
+  timestamp: string
+  signatureHeader: string
+}
+
+/**
+ * Constant-time verification of the X-ConfirmX-Signature header against
+ * HMAC-SHA256(secret, `${timestamp}.${body}`).
+ *
+ * Returns false on any mismatch, length mismatch, or non-string input.
+ * Never throws.
+ */
+export function verifyPayload(opts: VerifyOpts): boolean {
+  const { secret, body, timestamp, signatureHeader } = opts
+
+  if (typeof secret !== 'string' || typeof body !== 'string') return false
+  if (typeof timestamp !== 'string' || typeof signatureHeader !== 'string') {
+    return false
+  }
+
+  const expected =
+    'sha256=' + createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex')
+
+  const expectedBuf = Buffer.from(expected, 'utf8')
+  const providedBuf = Buffer.from(signatureHeader, 'utf8')
+  if (expectedBuf.length !== providedBuf.length) return false
+  return timingSafeEqual(expectedBuf, providedBuf)
+}
+
+/**
+ * Returns the absolute skew (in seconds) between the supplied timestamp
+ * and now. Replay window enforced by ConfirmX is 300s.
+ */
+export function timestampSkewSeconds(timestamp: string, now: number = Date.now()): number {
+  const ts = parseInt(timestamp, 10)
+  if (!Number.isFinite(ts)) return Number.POSITIVE_INFINITY
+  return Math.abs(now / 1000 - ts)
+}
+
+/** Replay window in seconds — must match the receiver convention. */
+export const REPLAY_WINDOW_SECONDS = 300

package/types/api.d.ts

@@ -0,0 +1,199 @@
+/**
+ * TypeScript types mirroring the ConfirmX /api/v1/* response shapes.
+ *
+ * Kept intentionally loose (a lot of `any` on optional nested objects)
+ * because the runtime data is what matters — these exist for IDE help
+ * and downstream type-narrowing in node implementations.
+ *
+ * Verified against the ConfirmX API v1 as of 2026-06.
+ */
+/** Webhook event types accepted by /api/v1/webhooks. */
+export declare const WEBHOOK_EVENT_TYPES: readonly ["message.received", "conversation.created", "message.sent", "message.status", "template.status"];
+export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
+/** Envelope POSTed to subscribers by ConfirmX. The `data` shape varies by event type. */
+export interface WebhookEnvelope<T = any> {
+    id: string;
+    type: WebhookEventType;
+    createdAt: string;
+    organizationId: string;
+    data: T;
+}
+export interface Account {
+    id: string;
+    label: string;
+    phoneNumberId?: string;
+    businessAccountId?: string;
+    isActive: boolean;
+    createdAt: string;
+}
+export interface Template {
+    id: string;
+    name: string;
+    language: string;
+    status: 'PENDING' | 'APPROVED' | 'REJECTED';
+    category: string;
+    components: Array<Record<string, any>>;
+}
+export interface ConversationContact {
+    id: string;
+    phoneNumber: string;
+    name?: string | null;
+    tags?: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+export interface Conversation {
+    id: string;
+    whatsappAccountId: string;
+    whatsappContactId: string;
+    status: 'open' | 'resolved' | 'archived';
+    unreadCount: number;
+    lastMessageAt: string | null;
+    windowExpiresAt: string | null;
+    assignedToId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    contact?: ConversationContact;
+    account?: {
+        id: string;
+        label: string;
+        phoneNumberId?: string;
+    };
+    /** Latest message preview (list endpoint only embeds one). */
+    messages?: Array<Partial<Message>>;
+    assignedTo?: {
+        id: string;
+        name: string;
+    } | null;
+}
+export type MessageDirection = 'inbound' | 'outbound';
+export type MessageType = 'text' | 'image' | 'video' | 'document' | 'audio' | 'voice' | 'button' | 'template';
+export interface Message {
+    id: string;
+    wamid?: string | null;
+    whatsappConversationId: string;
+    direction: MessageDirection;
+    type: MessageType | string;
+    body?: string | null;
+    mediaUrl?: string | null;
+    mediaFilename?: string | null;
+    mediaMimeType?: string | null;
+    mediaCaption?: string | null;
+    replyToMessageId?: string | null;
+    status: string;
+    sentAt?: string | null;
+    deliveredAt?: string | null;
+    readAt?: string | null;
+    failedAt?: string | null;
+    failureReason?: string | null;
+    senderType: string;
+    sentByUserId?: string | null;
+    sentByApiKeyId?: string | null;
+    sentByApiLabel?: string | null;
+    sentByWorkflowId?: string | null;
+    sentByCampaignId?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    replyToMessage?: Pick<Message, 'id' | 'type' | 'body' | 'direction' | 'mediaFilename' | 'mediaMimeType'> | null;
+    sentByUser?: {
+        id: string;
+        name: string;
+    } | null;
+    sentByWorkflow?: {
+        id: string;
+        name: string;
+    } | null;
+    sentByCampaign?: {
+        id: string;
+        name: string;
+    } | null;
+}
+export interface ListMessagesResult {
+    messages: Message[];
+    nextCursor: string | null;
+}
+export interface WebhookSubscription {
+    id: string;
+    url: string;
+    events: WebhookEventType[];
+    isActive: boolean;
+    description: string | null;
+    failureCount: number;
+    lastDeliveredAt: string | null;
+    lastError: string | null;
+    createdAt: string;
+}
+export interface WebhookCreateResponse {
+    webhook: WebhookSubscription;
+    /** Plaintext signing secret — returned ONLY at create time. */
+    secret: string;
+    secretNote: string;
+}
+export interface MatchedZoneSuccess {
+    success: true;
+    governorate: {
+        id: string;
+        name: string;
+        externalId: string | null;
+        confidence: number;
+    };
+    area: {
+        id: string;
+        name: string;
+        externalId: string | null;
+        confidence: number;
+    } | null;
+    governorateCorrected?: boolean;
+    availableAreas?: string[];
+}
+export interface MatchedZoneGovernorateMissing {
+    success: false;
+    matched: false;
+    error: string;
+    input: {
+        governorate: string;
+        area?: string;
+    };
+    suggestions: string[];
+}
+export interface MatchedZoneAmbiguous {
+    success: false;
+    multipleMatches: true;
+    areaName: string;
+    options: Array<{
+        governorateId: string;
+        governorateName: string;
+        governorateExternalId: string | null;
+        areaId: string;
+        areaName: string;
+        areaExternalId: string | null;
+        confidence: number;
+    }>;
+    message: string;
+}
+export interface MatchedZoneError {
+    success: false;
+    error: string;
+}
+export type MatchedZone = MatchedZoneSuccess | MatchedZoneGovernorateMissing | MatchedZoneAmbiguous | MatchedZoneError;
+export interface GovernorateTreeNode {
+    id: string;
+    name: string;
+    nameEn: string | null;
+    aliases: string[];
+    externalId: string | null;
+    sortOrder: number;
+    areas: Array<{
+        id: string;
+        governorateId: string;
+        name: string;
+        nameEn: string | null;
+        aliases: string[];
+        externalId: string | null;
+        sortOrder: number;
+    }>;
+}
+export interface ListGovernoratesResult {
+    governorates: GovernorateTreeNode[];
+}

package/types/api.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * TypeScript types mirroring the ConfirmX /api/v1/* response shapes.
+ *
+ * Kept intentionally loose (a lot of `any` on optional nested objects)
+ * because the runtime data is what matters — these exist for IDE help
+ * and downstream type-narrowing in node implementations.
+ *
+ * Verified against the ConfirmX API v1 as of 2026-06.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_EVENT_TYPES = void 0;
+/** Webhook event types accepted by /api/v1/webhooks. */
+exports.WEBHOOK_EVENT_TYPES = [
+    'message.received',
+    'conversation.created',
+    'message.sent',
+    'message.status',
+    'template.status',
+];
+//# sourceMappingURL=api.js.map

package/types/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["api.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,wDAAwD;AAC3C,QAAA,mBAAmB,GAAG;IACjC,kBAAkB;IAClB,sBAAsB;IACtB,cAAc;IACd,gBAAgB;IAChB,iBAAiB;CACT,CAAA"}

package/types/api.ts

@@ -0,0 +1,238 @@
+/**
+ * TypeScript types mirroring the ConfirmX /api/v1/* response shapes.
+ *
+ * Kept intentionally loose (a lot of `any` on optional nested objects)
+ * because the runtime data is what matters — these exist for IDE help
+ * and downstream type-narrowing in node implementations.
+ *
+ * Verified against the ConfirmX API v1 as of 2026-06.
+ */
+
+/** Webhook event types accepted by /api/v1/webhooks. */
+export const WEBHOOK_EVENT_TYPES = [
+  'message.received',
+  'conversation.created',
+  'message.sent',
+  'message.status',
+  'template.status',
+] as const
+
+export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number]
+
+/** Envelope POSTed to subscribers by ConfirmX. The `data` shape varies by event type. */
+export interface WebhookEnvelope<T = any> {
+  id: string
+  type: WebhookEventType
+  createdAt: string
+  organizationId: string
+  data: T
+}
+
+// ============================================
+// Account
+// ============================================
+
+export interface Account {
+  id: string
+  label: string
+  phoneNumberId?: string
+  businessAccountId?: string
+  isActive: boolean
+  createdAt: string
+}
+
+// ============================================
+// Template
+// ============================================
+
+export interface Template {
+  id: string
+  name: string
+  language: string
+  status: 'PENDING' | 'APPROVED' | 'REJECTED'
+  category: string
+  components: Array<Record<string, any>>
+}
+
+// ============================================
+// Conversation
+// ============================================
+
+export interface ConversationContact {
+  id: string
+  phoneNumber: string
+  name?: string | null
+  tags?: Array<{ id: string; name: string }>
+}
+
+export interface Conversation {
+  id: string
+  whatsappAccountId: string
+  whatsappContactId: string
+  status: 'open' | 'resolved' | 'archived'
+  unreadCount: number
+  lastMessageAt: string | null
+  windowExpiresAt: string | null
+  assignedToId: string | null
+  createdAt: string
+  updatedAt: string
+  contact?: ConversationContact
+  account?: { id: string; label: string; phoneNumberId?: string }
+  /** Latest message preview (list endpoint only embeds one). */
+  messages?: Array<Partial<Message>>
+  assignedTo?: { id: string; name: string } | null
+}
+
+// ============================================
+// Message
+// ============================================
+
+export type MessageDirection = 'inbound' | 'outbound'
+export type MessageType =
+  | 'text'
+  | 'image'
+  | 'video'
+  | 'document'
+  | 'audio'
+  | 'voice'
+  | 'button'
+  | 'template'
+
+export interface Message {
+  id: string
+  wamid?: string | null
+  whatsappConversationId: string
+  direction: MessageDirection
+  type: MessageType | string
+  body?: string | null
+  mediaUrl?: string | null
+  mediaFilename?: string | null
+  mediaMimeType?: string | null
+  mediaCaption?: string | null
+  replyToMessageId?: string | null
+  status: string
+  sentAt?: string | null
+  deliveredAt?: string | null
+  readAt?: string | null
+  failedAt?: string | null
+  failureReason?: string | null
+  senderType: string
+  sentByUserId?: string | null
+  sentByApiKeyId?: string | null
+  sentByApiLabel?: string | null
+  sentByWorkflowId?: string | null
+  sentByCampaignId?: string | null
+  createdAt: string
+  updatedAt: string
+  replyToMessage?: Pick<Message, 'id' | 'type' | 'body' | 'direction' | 'mediaFilename' | 'mediaMimeType'> | null
+  sentByUser?: { id: string; name: string } | null
+  sentByWorkflow?: { id: string; name: string } | null
+  sentByCampaign?: { id: string; name: string } | null
+}
+
+export interface ListMessagesResult {
+  messages: Message[]
+  nextCursor: string | null
+}
+
+// ============================================
+// Webhook subscription
+// ============================================
+
+export interface WebhookSubscription {
+  id: string
+  url: string
+  events: WebhookEventType[]
+  isActive: boolean
+  description: string | null
+  failureCount: number
+  lastDeliveredAt: string | null
+  lastError: string | null
+  createdAt: string
+}
+
+export interface WebhookCreateResponse {
+  webhook: WebhookSubscription
+  /** Plaintext signing secret — returned ONLY at create time. */
+  secret: string
+  secretNote: string
+}
+
+// ============================================
+// Shipping zone matcher
+// ============================================
+
+export interface MatchedZoneSuccess {
+  success: true
+  governorate: {
+    id: string
+    name: string
+    externalId: string | null
+    confidence: number
+  }
+  area: {
+    id: string
+    name: string
+    externalId: string | null
+    confidence: number
+  } | null
+  governorateCorrected?: boolean
+  availableAreas?: string[]
+}
+
+export interface MatchedZoneGovernorateMissing {
+  success: false
+  matched: false
+  error: string
+  input: { governorate: string; area?: string }
+  suggestions: string[]
+}
+
+export interface MatchedZoneAmbiguous {
+  success: false
+  multipleMatches: true
+  areaName: string
+  options: Array<{
+    governorateId: string
+    governorateName: string
+    governorateExternalId: string | null
+    areaId: string
+    areaName: string
+    areaExternalId: string | null
+    confidence: number
+  }>
+  message: string
+}
+
+export interface MatchedZoneError {
+  success: false
+  error: string
+}
+
+export type MatchedZone =
+  | MatchedZoneSuccess
+  | MatchedZoneGovernorateMissing
+  | MatchedZoneAmbiguous
+  | MatchedZoneError
+
+export interface GovernorateTreeNode {
+  id: string
+  name: string
+  nameEn: string | null
+  aliases: string[]
+  externalId: string | null
+  sortOrder: number
+  areas: Array<{
+    id: string
+    governorateId: string
+    name: string
+    nameEn: string | null
+    aliases: string[]
+    externalId: string | null
+    sortOrder: number
+  }>
+}
+
+export interface ListGovernoratesResult {
+  governorates: GovernorateTreeNode[]
+}