@ixblix/sdk-js 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Shared types for the ixblix SDK.
+ *
+ * These types mirror the ixblix public REST API. They are intentionally
+ * self-contained (no dependency on any private package) so the SDK can be
+ * published and consumed by any desk/CRM integration.
+ */
+/** Who sent a message. */
+export type SenderType = "CONTACT" | "COMPANY" | "SYSTEM";
+/** Lifecycle state of the E2EE key exchange for a conversation. */
+export type ConversationKeyStatus = "AWAITING_OPERATOR" | "AWAITING_CUSTOMER" | "ACTIVE";
+/** Lifecycle state of a conversation. */
+export type ConversationStatus = "ACTIVE" | "CLOSED" | "EXPIRED";
+/** Consent state of a contact (LGPD). */
+export type ConsentStatus = "PENDING" | "GRANTED" | "DENIED" | "REVOKED";
+/** A contact (customer) in a conversation. */
+export interface Contact {
+    id: string;
+    externalId: string;
+    name?: string;
+    phone?: string;
+    email?: string;
+    consentStatus: ConsentStatus;
+}
+/** Payload used to create a conversation for a contact. */
+export interface ContactInput {
+    /** Unique identifier of the contact in the original channel. */
+    externalId: string;
+    name?: string;
+    phone?: string;
+    email?: string;
+    /** Free-form metadata from the CRM. */
+    metadata?: Record<string, unknown>;
+}
+/** A conversation as returned by the ixblix API. */
+export interface Conversation {
+    id: string;
+    token: string;
+    status: ConversationStatus;
+    keyStatus: ConversationKeyStatus;
+    sourceChannel: string;
+    createdAt: string;
+}
+/** Company branding customizations (white-label). */
+export interface CompanyCustomization {
+    id: string;
+    brandName?: string;
+    logoUrl?: string;
+    primaryColor?: string;
+    faviconUrl?: string;
+    welcomeMessage?: string;
+}
+/** Company summary returned when creating a conversation. */
+export interface CompanySummary {
+    id: string;
+    name: string;
+    customizations?: CompanyCustomization;
+}
+/** Result of creating a conversation. */
+export interface CreateConversationResult {
+    conversation: Conversation;
+    contact: Contact;
+    /** URL to share with the contact so they can join the secure chat. */
+    deeplink: string;
+    company: CompanySummary;
+}
+/** Current E2EE key state of a conversation (operator view). */
+export interface ConversationKeys {
+    conversationId: string;
+    keyStatus: ConversationKeyStatus;
+    operatorPublicKey: string | null;
+    customerPublicKey: string | null;
+}
+/** Result of registering the customer's public key. */
+export interface RegisterCustomerKeyResult {
+    conversationId: string;
+    keyStatus: ConversationKeyStatus;
+}
+/** Result of erasing a conversation's encrypted content. */
+export interface EraseConversationResult {
+    conversationId: string;
+    deletedMessages: number;
+}
+/**
+ * Cryptographic envelope attached to an encrypted message or media file.
+ *
+ * The ixblix backend only ever stores and relays these fields — it never sees the
+ * plaintext content nor any private key. `content` holds the base64 AES-GCM
+ * ciphertext; `encryptedKey` holds the per-message AES key wrapped to the
+ * recipient's RSA-OAEP public key, and `selfEncryptedKey` holds the same AES
+ * key wrapped to the sender's own public key so the sender can read back its
+ * own sent messages.
+ */
+export interface MessageEnvelope {
+    /** Base64 AES-256-GCM ciphertext of the plaintext content. */
+    content: string;
+    /** Base64 AES-GCM initialization vector (12 bytes). */
+    iv: string;
+    /** Base64 AES-GCM authentication tag (16 bytes). */
+    authTag: string;
+    /** Base64 RSA-OAEP-wrapped per-message AES key (to the recipient). */
+    encryptedKey: string;
+    /** Base64 RSA-OAEP-wrapped per-message AES key (to the sender, for self-read). */
+    selfEncryptedKey: string;
+    /** Identifier of the sender's public key. */
+    keyId: string;
+}
+/** A message as returned by the ixblix API. */
+export interface Message {
+    id: string;
+    conversationId: string;
+    senderType: SenderType;
+    /** Plaintext for legacy/system messages, or base64 ciphertext when encrypted. */
+    content: string;
+    contentType: string;
+    /** True when `content` is ciphertext and the envelope fields are populated. */
+    contentEncrypted: boolean;
+    keyId?: string;
+    iv?: string;
+    authTag?: string;
+    encryptedKey?: string;
+    selfEncryptedKey?: string;
+    /** Present when the message carries an attached media file. */
+    mediaId?: string;
+    media?: Media;
+    sentAt: string;
+}
+/** Metadata of a media file attached to a message. */
+export interface Media {
+    id: string;
+    companyId: string;
+    conversationId: string;
+    messageId?: string;
+    mimeType: string;
+    fileName: string;
+    sizeBytes: number;
+    iv?: string;
+    authTag?: string;
+    encryptedKey?: string;
+    selfEncryptedKey?: string;
+    keyId?: string;
+    createdAt: string;
+}
+/** A subscription plan offered by ixblix. */
+export interface Plan {
+    id: string;
+    name: string;
+    description?: string;
+    billingType: "MESSAGES" | "CONVERSATIONS" | "COMPANY" | "TIME" | "CHANNEL";
+    includedConversations?: number | null;
+    includedMessages?: number | null;
+    durationDays?: number | null;
+    priceCents: number;
+    overagePriceCents?: number | null;
+    isActive: boolean;
+    isPublic: boolean;
+    createdAt: string;
+}
+/** Company registration payload (keyless onboarding). */
+export interface RegisterCompanyInput {
+    name: string;
+    slug: string;
+    planId?: string;
+    paymentProvider?: string;
+    confirmationWebhookUrl?: string;
+}
+/** Payment instructions returned when registering a company. */
+export interface PaymentInstructions {
+    transactionId: string;
+    provider: string;
+    amountCents: number;
+    currency: string;
+    confirmationUrl: string;
+    status: string;
+}
+/** Result of registering a company. */
+export interface RegisterCompanyResult {
+    company: {
+        id: string;
+        name: string;
+        slug: string;
+        status: string;
+        planId?: string;
+        createdAt: string;
+    };
+    payment: PaymentInstructions;
+}
+/** Result of activating a company (payment confirmed). */
+export interface ActivateCompanyResult {
+    apiKey: string;
+    status: string;
+}
+/** Company balance / plan state. */
+export interface CompanyBalance {
+    id: string;
+    name: string;
+    balanceCents: number;
+    planId?: string;
+    planExpiresAt?: string;
+}
+/** A credit purchase record. */
+export interface CreditPurchase {
+    id: string;
+    companyId: string;
+    amountCents: number;
+    currency: string;
+    provider: string;
+    providerTransactionId?: string;
+    status: "PENDING" | "COMPLETED" | "FAILED" | "REFUNDED";
+    metadata?: Record<string, unknown>;
+    purchasedAt: string;
+    createdAt: string;
+}
+/** Result of purchasing credits. */
+export interface PurchaseCreditsResult {
+    purchase: CreditPurchase;
+    result: {
+        success: boolean;
+        transactionId?: string;
+        provider?: string;
+    };
+}
+/** Available payment providers. */
+export interface PaymentProvidersResult {
+    providers: string[];
+}
+/** Payload relayed from the original channel via webhook. */
+export interface OriginalChannelMessageInput {
+    conversationId: string;
+    /** Base64 AES-GCM ciphertext (end-to-end encrypted). */
+    content: string;
+    iv: string;
+    authTag: string;
+    encryptedKey: string;
+    selfEncryptedKey: string;
+    keyId: string;
+    /** Free-form metadata from the original channel (e.g. channelMessageId). */
+    metadata?: Record<string, unknown>;
+}
+/** Webhook event payloads ixblix may deliver to a company. */
+export type WebhookEvent = CompanyActivatedEvent | MessageReceivedEvent | MessageReadEvent | CustomerJoinedEvent | ConversationClosedEvent | PresenceEvent | BalanceLowEvent;
+/** Delivered when a company is activated after payment confirmation. */
+export interface CompanyActivatedEvent {
+    event: "COMPANY_ACTIVATED";
+    companyId: string;
+    transactionId: string;
+    apiKey: string;
+}
+/** Delivered when a contact sends a message (text or media). */
+export interface MessageReceivedEvent {
+    event: "MESSAGE_RECEIVED";
+    companyId: string;
+    conversationId: string;
+    messageId: string;
+    sentAt: string;
+}
+/** Delivered when the customer reads a company-sent message. */
+export interface MessageReadEvent {
+    event: "MESSAGE_READ";
+    companyId: string;
+    conversationId: string;
+    messageId: string;
+    readAt: string;
+}
+/** Delivered when the customer joins the secure conversation and registers its public key. */
+export interface CustomerJoinedEvent {
+    event: "CUSTOMER_JOINED";
+    companyId: string;
+    conversationId: string;
+    customerPublicKey: string;
+}
+/** Delivered when a conversation is closed. */
+export interface ConversationClosedEvent {
+    event: "CONVERSATION_CLOSED";
+    companyId: string;
+    conversationId: string;
+}
+/** Presence/metadata event reported by the customer's chat window. */
+export interface PresenceEvent {
+    event: "TYPING" | "STOPPED_TYPING" | "RECORDING" | "CHAT_CLOSED";
+    companyId: string;
+    conversationId: string;
+    /** Human-readable presence type. */
+    type: "typing" | "stopped" | "recording" | "chat_closed";
+}
+/** Delivered when the company credit balance is low. */
+export interface BalanceLowEvent {
+    event: "BALANCE_LOW";
+    companyId: string;
+    balanceCents: number;
+}
+/** Standard ixblix error payload. */
+export interface IxblixErrorBody {
+    error: string;
+    code: string;
+    errors?: Array<{
+        path: string;
+        message: string;
+    }>;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared types for the ixblix SDK.
+ *
+ * These types mirror the ixblix public REST API. They are intentionally
+ * self-contained (no dependency on any private package) so the SDK can be
+ * published and consumed by any desk/CRM integration.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/webhooks.d.ts

@@ -0,0 +1,35 @@
+import type { WebhookEvent } from "./types.js";
+/** Header carrying the HMAC-SHA256 signature of the raw body. */
+export declare const WEBHOOK_SIGNATURE_HEADER = "X-Ixblix-Signature";
+/** Header carrying the event id (for idempotent receivers). */
+export declare const WEBHOOK_ID_HEADER = "X-Ixblix-Event-Id";
+/** Header carrying the event type. */
+export declare const WEBHOOK_EVENT_HEADER = "X-Ixblix-Event";
+/** Result of parsing a webhook payload. */
+export interface ParsedWebhook<T extends WebhookEvent = WebhookEvent> {
+    /** The parsed, validated event. */
+    event: T;
+    /** The raw payload as received. */
+    raw: unknown;
+}
+/**
+ * Parse and validate an ixblix webhook payload.
+ *
+ * @param body The raw request body (already JSON-parsed).
+ * @returns The typed event.
+ * @throws {Error} When the payload is not a recognized ixblix webhook event.
+ */
+export declare function parseWebhook(body: unknown): ParsedWebhook;
+/**
+ * Verify an ixblix webhook request.
+ *
+ * Computes the HMAC-SHA256 signature of the raw body using the shared secret
+ * and compares it (in constant time) against the `X-Ixblix-Signature` header.
+ * Throws when the signature is missing or does not match.
+ *
+ * @param body The raw request body (already JSON-parsed).
+ * @param secret The company's webhook secret (from `whsec_...`).
+ * @param signature The signature from the `X-Ixblix-Signature` header.
+ * @returns The typed, validated event.
+ */
+export declare function verifyWebhook(body: unknown, secret: string, signature?: string): ParsedWebhook;

package/dist/webhooks.js

@@ -0,0 +1,78 @@
+/**
+ * Helpers for receiving ixblix webhooks.
+ *
+ * ixblix signs webhook payloads with HMAC-SHA256 using the company's webhook
+ * secret. The signature is sent in the `X-Ixblix-Signature` header. Integrations
+ * should call {@link verifyWebhook} with the raw body and the secret to
+ * authenticate the request before acting on it.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** Header carrying the HMAC-SHA256 signature of the raw body. */
+export const WEBHOOK_SIGNATURE_HEADER = "X-Ixblix-Signature";
+/** Header carrying the event id (for idempotent receivers). */
+export const WEBHOOK_ID_HEADER = "X-Ixblix-Event-Id";
+/** Header carrying the event type. */
+export const WEBHOOK_EVENT_HEADER = "X-Ixblix-Event";
+/**
+ * Parse and validate an ixblix webhook payload.
+ *
+ * @param body The raw request body (already JSON-parsed).
+ * @returns The typed event.
+ * @throws {Error} When the payload is not a recognized ixblix webhook event.
+ */
+export function parseWebhook(body) {
+    if (typeof body !== "object" || body === null) {
+        throw new Error("ixblix webhook payload must be a JSON object");
+    }
+    const record = body;
+    const event = record.event;
+    if (typeof event !== "string") {
+        throw new Error("ixblix webhook payload is missing the 'event' field");
+    }
+    switch (event) {
+        case "COMPANY_ACTIVATED":
+        case "MESSAGE_RECEIVED":
+        case "MESSAGE_READ":
+        case "CUSTOMER_JOINED":
+        case "CONVERSATION_CLOSED":
+        case "TYPING":
+        case "STOPPED_TYPING":
+        case "RECORDING":
+        case "CHAT_CLOSED":
+        case "BALANCE_LOW":
+            return { event: body, raw: body };
+        default:
+            throw new Error(`Unknown ixblix webhook event: ${event}`);
+    }
+}
+/**
+ * Verify an ixblix webhook request.
+ *
+ * Computes the HMAC-SHA256 signature of the raw body using the shared secret
+ * and compares it (in constant time) against the `X-Ixblix-Signature` header.
+ * Throws when the signature is missing or does not match.
+ *
+ * @param body The raw request body (already JSON-parsed).
+ * @param secret The company's webhook secret (from `whsec_...`).
+ * @param signature The signature from the `X-Ixblix-Signature` header.
+ * @returns The typed, validated event.
+ */
+export function verifyWebhook(body, secret, signature) {
+    if (!signature) {
+        throw new Error("ixblix webhook is missing the X-Ixblix-Signature header; cannot verify authenticity");
+    }
+    if (!secret) {
+        throw new Error("A webhook secret is required to verify ixblix webhook signatures");
+    }
+    const expected = createHmac("sha256", secret)
+        .update(JSON.stringify(body))
+        .digest("hex");
+    const expectedBuf = Buffer.from(expected, "hex");
+    const receivedBuf = Buffer.from(signature, "hex");
+    if (expectedBuf.length !== receivedBuf.length ||
+        !timingSafeEqual(expectedBuf, receivedBuf)) {
+        throw new Error("ixblix webhook signature verification failed");
+    }
+    return parseWebhook(body);
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG1D,iEAAiE;AACjE,MAAM,CAAC,MAAM,wBAAwB,GAAG,oBAAoB,CAAC;AAC7D,+DAA+D;AAC/D,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AACrD,sCAAsC;AACtC,MAAM,CAAC,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAUrD;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IACD,MAAM,MAAM,GAAG,IAA+B,CAAC;IAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IAED,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,mBAAmB,CAAC;QACzB,KAAK,kBAAkB,CAAC;QACxB,KAAK,cAAc,CAAC;QACpB,KAAK,iBAAiB,CAAC;QACvB,KAAK,qBAAqB,CAAC;QAC3B,KAAK,QAAQ,CAAC;QACd,KAAK,gBAAgB,CAAC;QACtB,KAAK,WAAW,CAAC;QACjB,KAAK,aAAa,CAAC;QACnB,KAAK,aAAa;YAChB,OAAO,EAAE,KAAK,EAAE,IAAoB,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;QACpD;YACE,MAAM,IAAI,KAAK,CAAC,iCAAiC,KAAK,EAAE,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAa,EACb,MAAc,EACd,SAAkB;IAElB,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,kEAAkE,CACnE,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC;SAC1C,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;SAC5B,MAAM,CAAC,KAAK,CAAC,CAAC;IACjB,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACjD,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAClD,IACE,WAAW,CAAC,MAAM,KAAK,WAAW,CAAC,MAAM;QACzC,CAAC,eAAe,CAAC,WAAW,EAAE,WAAW,CAAC,EAC1C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ixblix/sdk-js",
+  "version": "0.2.0",
+  "description": "Official ixblix SDK for desk/CRM integrations. Create overflow conversations, exchange end-to-end encrypted messages and media, and manage company onboarding.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ixblix/ixblix-sdk-js.git"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "test": "vitest run",
+    "test:e2e": "tsx src/e2e.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ixblix",
+    "messaging",
+    "overflow",
+    "desk",
+    "crm",
+    "e2ee",
+    "encryption"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}