@dereekb/zoho 13.3.0 → 13.4.0

package/nestjs/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@dereekb/zoho/nestjs",
-  "version": "13.3.0",
+  "version": "13.4.0",
   "peerDependencies": {
-    "@dereekb/util": "13.3.0",
-    "@dereekb/zoho": "13.3.0",
-    "@nestjs/common": "^11.0.0",
-    "@nestjs/config": "^4.0.0"
+    "@dereekb/nestjs": "13.4.0",
+    "@dereekb/util": "13.4.0",
+    "@dereekb/zoho": "13.4.0",
+    "@nestjs/common": "^11.1.16",
+    "@nestjs/config": "^4.0.3",
+    "express": "^5.0.0"
   },
   "devDependencies": {
-    "@nestjs/testing": "^11.0.0",
+    "@nestjs/testing": "^11.1.14",
     "date-fns": "^4.0.0"
   },
   "exports": {

package/nestjs/src/lib/sign/index.d.ts

@@ -1,3 +1,4 @@
 export * from './sign.api';
 export * from './sign.config';
 export * from './sign.module';
+export * from './webhook';

package/nestjs/src/lib/sign/webhook/index.d.ts

@@ -0,0 +1,6 @@
+export * from './webhook.zoho.sign';
+export * from './webhook.zoho.sign.config';
+export * from './webhook.zoho.sign.controller';
+export * from './webhook.zoho.sign.module';
+export * from './webhook.zoho.sign.service';
+export * from './webhook.zoho.sign.verify';

package/nestjs/src/lib/sign/webhook/webhook.zoho.sign.config.d.ts

@@ -0,0 +1,11 @@
+export declare const ZOHO_SIGN_WEBHOOK_SECRET_TOKEN_ENV_VAR = "ZOHO_SIGN_WEBHOOK_SECRET_TOKEN";
+export interface ZohoSignWebhookConfig {
+    readonly webhookSecret: string;
+}
+/**
+ * Configuration for the Zoho Sign webhook service.
+ */
+export declare abstract class ZohoSignWebhookServiceConfig {
+    readonly zohoSignWebhook: ZohoSignWebhookConfig;
+    static assertValidConfig(config: ZohoSignWebhookServiceConfig): void;
+}

package/nestjs/src/lib/sign/webhook/webhook.zoho.sign.controller.d.ts

@@ -0,0 +1,8 @@
+import { type RawBodyBuffer } from '@dereekb/nestjs';
+import { type Request } from 'express';
+import { ZohoSignWebhookService } from './webhook.zoho.sign.service';
+export declare class ZohoSignWebhookController {
+    private readonly _zohoSignWebhookService;
+    constructor(zohoSignWebhookService: ZohoSignWebhookService);
+    handleZohoSignWebhook(req: Request, rawBody: RawBodyBuffer): Promise<void>;
+}

package/nestjs/src/lib/sign/webhook/webhook.zoho.sign.d.ts

@@ -0,0 +1,124 @@
+import { type HandlerBindAccessor, type HandlerMappedSetFunction, type Handler, type EmailAddress } from '@dereekb/util';
+import { type ZohoSignRequestId, type ZohoSignDocumentId, type ZohoSignActionId, type ZohoSignRequestStatus, type ZohoSignRequestTypeId } from '@dereekb/zoho';
+/**
+ * Zoho Sign webhook operation type constants.
+ *
+ * These correspond to the `operation_type` field in the webhook `notifications` payload.
+ */
+export type ZohoSignWebhookOperationType = 'RequestSubmitted' | 'RequestViewed' | 'RequestSigningSuccess' | 'RequestCompleted' | 'RequestRejected' | 'RequestRecalled' | 'RequestForwarded' | 'RequestExpired';
+/**
+ * The `notifications` portion of a Zoho Sign webhook payload.
+ *
+ * Contains details about the action performed on the document.
+ */
+export interface ZohoSignWebhookNotification {
+    /**
+     * Email address of the person who performed the operation.
+     */
+    readonly performed_by_email: EmailAddress;
+    /**
+     * Name of the person who performed the operation.
+     */
+    readonly performed_by_name: string;
+    /**
+     * Timestamp of the operation in Java milliseconds.
+     */
+    readonly performed_at: number;
+    /**
+     * Reason stated for the operation, if applicable.
+     */
+    readonly reason?: string;
+    /**
+     * Short description of the activity performed.
+     */
+    readonly activity: string;
+    /**
+     * The type of operation that triggered this webhook.
+     */
+    readonly operation_type: ZohoSignWebhookOperationType;
+    /**
+     * Sign action ID of the signer.
+     *
+     * Present for signer-related actions: RequestViewed, RequestSigningSuccess,
+     * RequestRejected, and RequestForwarded.
+     */
+    readonly action_id?: ZohoSignActionId;
+    /**
+     * IP address captured during this operation.
+     */
+    readonly ip_address?: string;
+}
+/**
+ * A document reference within the webhook request data.
+ */
+export interface ZohoSignWebhookDocumentRef {
+    readonly document_name: string;
+    readonly document_id: ZohoSignDocumentId;
+}
+/**
+ * The `requests` portion of a Zoho Sign webhook payload.
+ *
+ * Contains details about the document for which the webhook was triggered.
+ */
+export interface ZohoSignWebhookRequestData {
+    readonly request_status: ZohoSignRequestStatus;
+    readonly request_name: string;
+    readonly request_id: ZohoSignRequestId;
+    readonly org_id?: string;
+    readonly request_type_id?: ZohoSignRequestTypeId;
+    readonly document_ids: ZohoSignWebhookDocumentRef[];
+}
+/**
+ * The complete webhook payload from Zoho Sign.
+ *
+ * Contains two top-level keys: `notifications` (the action details) and
+ * `requests` (the document details).
+ *
+ * @example
+ * ```json
+ * {
+ *   "notifications": {
+ *     "performed_by_email": "testuser@zoho.com",
+ *     "performed_at": 1555062604837,
+ *     "activity": "Document has been signed",
+ *     "operation_type": "RequestSigningSuccess",
+ *     "action_id": "1000000000090",
+ *     "performed_by_name": "test user"
+ *   },
+ *   "requests": {
+ *     "request_name": "NDA Document",
+ *     "request_id": "1000000000000",
+ *     "request_status": "inprogress",
+ *     "document_ids": [{ "document_name": "CommonNDA.pdf", "document_id": "100000000000050" }]
+ *   }
+ * }
+ * ```
+ */
+export interface ZohoSignWebhookPayload {
+    readonly notifications: ZohoSignWebhookNotification;
+    readonly requests: ZohoSignWebhookRequestData;
+}
+/**
+ * A parsed Zoho Sign webhook event, providing convenient access to the operation type.
+ */
+export type ZohoSignWebhookEvent<T extends ZohoSignWebhookOperationType = ZohoSignWebhookOperationType> = ZohoSignWebhookPayload & {
+    readonly operationType: T;
+};
+/**
+ * Creates a {@link ZohoSignWebhookEvent} from a raw payload.
+ */
+export declare function zohoSignWebhookEvent(payload: ZohoSignWebhookPayload): ZohoSignWebhookEvent;
+export type ZohoSignEventHandler = Handler<ZohoSignWebhookEvent, ZohoSignWebhookOperationType>;
+export declare const zohoSignEventHandlerFactory: import("@dereekb/util").HandlerFactory<ZohoSignWebhookEvent<ZohoSignWebhookOperationType>, ZohoSignWebhookOperationType, boolean>;
+export type ZohoSignHandlerMappedSetFunction<T extends ZohoSignWebhookOperationType = ZohoSignWebhookOperationType> = HandlerMappedSetFunction<ZohoSignWebhookEvent<T>>;
+export interface ZohoSignEventHandlerConfigurer extends HandlerBindAccessor<ZohoSignWebhookEvent, ZohoSignWebhookOperationType> {
+    readonly handleRequestSubmitted: ZohoSignHandlerMappedSetFunction<'RequestSubmitted'>;
+    readonly handleRequestViewed: ZohoSignHandlerMappedSetFunction<'RequestViewed'>;
+    readonly handleRequestSigningSuccess: ZohoSignHandlerMappedSetFunction<'RequestSigningSuccess'>;
+    readonly handleRequestCompleted: ZohoSignHandlerMappedSetFunction<'RequestCompleted'>;
+    readonly handleRequestRejected: ZohoSignHandlerMappedSetFunction<'RequestRejected'>;
+    readonly handleRequestRecalled: ZohoSignHandlerMappedSetFunction<'RequestRecalled'>;
+    readonly handleRequestForwarded: ZohoSignHandlerMappedSetFunction<'RequestForwarded'>;
+    readonly handleRequestExpired: ZohoSignHandlerMappedSetFunction<'RequestExpired'>;
+}
+export declare const zohoSignEventHandlerConfigurerFactory: import("@dereekb/util").HandlerConfigurerFactory<ZohoSignEventHandlerConfigurer, ZohoSignWebhookEvent<ZohoSignWebhookOperationType>, ZohoSignWebhookOperationType, boolean>;

package/nestjs/src/lib/sign/webhook/webhook.zoho.sign.module.d.ts

@@ -0,0 +1,13 @@
+import { ZohoSignWebhookServiceConfig } from './webhook.zoho.sign.config';
+import { ConfigService } from '@nestjs/config';
+/**
+ * Reads the Zoho Sign webhook secret from the NestJS ConfigService
+ * and returns a validated webhook service config.
+ *
+ * @param configService - NestJS config service populated with webhook environment variables
+ * @returns Validated Zoho Sign webhook service configuration
+ * @throws {Error} If the webhook secret is not configured
+ */
+export declare function zohoSignWebhookServiceConfigFactory(configService: ConfigService): ZohoSignWebhookServiceConfig;
+export declare class ZohoSignWebhookModule {
+}

package/nestjs/src/lib/sign/webhook/webhook.zoho.sign.service.d.ts

@@ -0,0 +1,16 @@
+import { type Request } from 'express';
+import { type ZohoSignWebhookEvent, type ZohoSignWebhookOperationType } from './webhook.zoho.sign';
+import { type Handler } from '@dereekb/util';
+import { ZohoSignWebhookServiceConfig } from './webhook.zoho.sign.config';
+/**
+ * Service that handles Zoho Sign webhook events.
+ */
+export declare class ZohoSignWebhookService {
+    private readonly logger;
+    private readonly _verifier;
+    readonly handler: Handler<ZohoSignWebhookEvent, ZohoSignWebhookOperationType>;
+    readonly configure: import("@dereekb/util").HandlerConfigurer<import("./webhook.zoho.sign").ZohoSignEventHandlerConfigurer, ZohoSignWebhookEvent<ZohoSignWebhookOperationType>, ZohoSignWebhookOperationType, boolean>;
+    constructor(zohoSignWebhookServiceConfig: ZohoSignWebhookServiceConfig);
+    updateForWebhook(req: Request, rawBody: Buffer): Promise<void>;
+    updateForZohoSignEvent(event: ZohoSignWebhookEvent): Promise<void>;
+}

package/nestjs/src/lib/sign/webhook/webhook.zoho.sign.verify.d.ts

@@ -0,0 +1,45 @@
+import { type Request } from 'express';
+import { type ZohoSignWebhookEvent } from './webhook.zoho.sign';
+/**
+ * Header name used by Zoho Sign to send the HMAC signature.
+ */
+export declare const ZOHO_SIGN_WEBHOOK_SIGNATURE_HEADER = "x-zs-webhook-signature";
+export interface ZohoSignWebhookVerificationConfig {
+    /**
+     * Secret key configured in Zoho Sign webhook settings.
+     */
+    readonly secret: string;
+}
+export type ZohoSignWebhookEventVerificationResult = ZohoSignWebhookEventVerificationSuccessResult | ZohoSignWebhookEventVerificationErrorResult;
+export interface ZohoSignWebhookEventVerificationSuccessResult {
+    readonly valid: true;
+    readonly event: ZohoSignWebhookEvent;
+}
+export interface ZohoSignWebhookEventVerificationErrorResult {
+    readonly valid: false;
+}
+/**
+ * Function that verifies a Zoho Sign webhook event.
+ */
+export type ZohoSignWebhookEventVerifier = (req: Request, rawBody: Buffer) => Promise<ZohoSignWebhookEventVerificationResult>;
+/**
+ * Creates a verifier for Zoho Sign webhook events using HMAC-SHA256 signature verification.
+ *
+ * Zoho Sign computes `base64(HMAC-SHA256(payload, secret))` and sends the result
+ * in the `X-ZS-WEBHOOK-SIGNATURE` header. This verifier recomputes the signature
+ * from the raw request body and compares using timing-safe equality.
+ *
+ * @param config - Configuration containing the webhook secret key
+ * @returns A function that verifies webhook requests
+ *
+ * @example
+ * ```typescript
+ * const verifier = zohoSignWebhookEventVerifier({ secret: 'my-secret-key' });
+ * const result = await verifier(req, rawBody);
+ *
+ * if (result.valid) {
+ *   console.log(result.event.operationType);
+ * }
+ * ```
+ */
+export declare function zohoSignWebhookEventVerifier(config: ZohoSignWebhookVerificationConfig): ZohoSignWebhookEventVerifier;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/zoho",
-  "version": "13.3.0",
+  "version": "13.4.0",
   "exports": {
     "./nestjs": {
       "module": "./nestjs/index.esm.js",
@@ -17,13 +17,15 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "13.3.0",
-    "@nestjs/common": "^11.0.0",
-    "@nestjs/config": "^4.0.0",
+    "@dereekb/nestjs": "13.4.0",
+    "@dereekb/util": "13.4.0",
+    "@nestjs/common": "^11.1.16",
+    "@nestjs/config": "^4.0.3",
+    "express": "^5.0.0",
     "make-error": "^1.3.0"
   },
   "devDependencies": {
-    "@nestjs/testing": "^11.0.0",
+    "@nestjs/testing": "^11.1.14",
     "date-fns": "^4.0.0"
   },
   "module": "./index.esm.js",