@sakeetech/viva-payments-core 0.2.1

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

@@ -0,0 +1,447 @@
+/**
+ * Webhook event types and payloads for the Viva Wallet ISV integration.
+ *
+ * Covers: WebhookEnvelope<T> generic, EVENT_TYPES const object, and typed
+ * EventData payloads for v1-scope event types:
+ *   1796 — Transaction Payment Created
+ *   1797 — Transaction Reversal Created
+ *   1798 — Transaction Failed
+ *   4865 — Order Updated (cancellation)
+ *   8193 — Account Connected
+ *   8194 — Account Verification Status Changed
+ *
+ * Event 7936 (Sale Transactions) is NOT in v1 scope per plan A8.
+ * HMAC verification only applies to 7936; not implemented in v1.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:141
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:158
+ * @see references/viva-docs/md/wh-transaction-failed.txt:162
+ * @see references/viva-docs/md/wh-account-connected.txt:150
+ * @see references/viva-docs/md/wh-account-verif-status-changed.txt:152
+ */
+import type { CurrencyCode, TransactionId, OrderCode } from './common.js';
+/**
+ * v1-scope Viva Webhook event type identifiers.
+ *
+ * Defined as `as const` object per requirement 4 — NOT a TypeScript enum.
+ * This avoids TypeScript enum pitfalls (numeric reverse-mapping, etc.).
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:141
+ */
+export declare const EVENT_TYPES: {
+    /** A customer payment has been successful. */
+    readonly TRANSACTION_PAYMENT_CREATED: 1796;
+    /** A customer refund has been successfully actioned. */
+    readonly TRANSACTION_REVERSAL_CREATED: 1797;
+    /** A customer payment failed. */
+    readonly TRANSACTION_FAILED: 1798;
+    /** An order was cancelled (API or Smart Checkout back button). */
+    readonly ORDER_UPDATED: 4865;
+    /** An account is successfully connected to the ISV account. */
+    readonly ACCOUNT_CONNECTED: 8193;
+    /** Verification status of a connected account changed. */
+    readonly ACCOUNT_VERIFICATION_STATUS_CHANGED: 8194;
+};
+/**
+ * Union type of all v1-scope EventTypeId numeric values.
+ */
+export type VivaEventTypeId = (typeof EVENT_TYPES)[keyof typeof EVENT_TYPES];
+/**
+ * Deferred event type IDs — documented for future implementation.
+ * NOT in v1 scope per plan A8 and the narrowed event-type set.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:141
+ */
+export declare const DEFERRED_EVENT_TYPES: {
+    /** Commission payment withdrawn by Viva. Post-v1. */
+    readonly TRANSACTION_PRICE_CALCULATED: 1799;
+    /** ECR integration only. Post-v1. */
+    readonly TRANSACTION_POS_ECR_SESSION_CREATED: 1802;
+    /** ECR integration only. Post-v1. */
+    readonly TRANSACTION_POS_ECR_SESSION_FAILED: 1803;
+    /** Wallet account balance change. Post-v1. */
+    readonly ACCOUNT_TRANSACTION_CREATED: 2054;
+    /** Bank transfer created. Post-v1. */
+    readonly COMMAND_BANK_TRANSFER_CREATED: 768;
+    /** Bank transfer executed. Post-v1. */
+    readonly COMMAND_BANK_TRANSFER_EXECUTED: 769;
+    /**
+     * Sale transactions report file available. NOT in v1 — HMAC-signed webhook
+     * distinct from transaction events. Re-add in v1.1 if needed.
+     *
+     * @see references/viva-docs/md/wh-sale-transactions.txt:118
+     */
+    readonly SALE_TRANSACTIONS: 7936;
+    /** Marketplace-only: a transfer has been made. Post-v1. */
+    readonly TRANSFER_CREATED: 8448;
+};
+/**
+ * Generic webhook envelope shape.
+ *
+ * All Viva webhook POSTs share the same outer envelope; only `EventData`
+ * varies by event type.
+ *
+ * Observed in two different docs:
+ * - wh-transaction-payment-created.txt line 158: has `RetryCount` and
+ *   `RetryDelayInSeconds` at the top level (inside EventData AND envelope).
+ * - wh-account-connected.txt line 150: does NOT show RetryCount at top level,
+ *   only inside EventData.
+ *
+ * TODO(impl): verify whether RetryCount/RetryDelayInSeconds are envelope-level
+ * fields on all event types or only on transaction events. Cross-check against
+ * live demo payload.
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:252
+ * @see references/viva-docs/md/wh-account-connected.txt:159
+ *
+ * The `Delay` field is documented as `string` in wh-account-connected.txt:231
+ * but shown as `null` in the example. Typed as `string | null`.
+ */
+export interface WebhookEnvelope<T> {
+    /** The webhook URL that received this notification. */
+    readonly Url: string;
+    /**
+     * The event-specific payload. Type varies by EventTypeId.
+     *
+     * @see references/viva-docs/md/wh-transaction-payment-created.txt:158
+     */
+    readonly EventData: T;
+    /**
+     * ISO 8601 UTC timestamp when the notification was initially created.
+     * Used for the 25-hour freshness check (plan A12).
+     *
+     * @see references/viva-docs/md/wh-transaction-payment-created.txt:252
+     */
+    readonly Created: string;
+    /**
+     * Viva internal tracking ID for cross-system log correlation.
+     * Store as `correlation_id` on structured log lines (plan A13).
+     *
+     * @see references/viva-docs/md/wh-account-connected.txt:159
+     */
+    readonly CorrelationId: string;
+    /**
+     * The type of event that triggered this notification.
+     *
+     * @see references/viva-docs/md/webhooks-for-payments.txt:141
+     */
+    readonly EventTypeId: number;
+    /**
+     * Delay timespan for messages sent at a future date (null for immediate).
+     *
+     * @see references/viva-docs/md/wh-account-connected.txt:161
+     */
+    readonly Delay: string | null;
+    /**
+     * Unique identifier of this message delivery.
+     * Used for deduplication at the DB layer (UNIQUE constraint on message_id).
+     *
+     * @see references/viva-docs/md/wh-account-connected.txt:164
+     */
+    readonly MessageId: string;
+    /**
+     * The recipient of the webhook (typically the ISV account Merchant ID).
+     *
+     * @see references/viva-docs/md/wh-account-connected.txt:165
+     */
+    readonly RecipientId: string;
+    /**
+     * Message type: always 512 (0x200) for merchant webhooks.
+     *
+     * @see references/viva-docs/md/wh-account-connected.txt:166
+     */
+    readonly MessageTypeId: number;
+    /**
+     * Number of retry attempts so far (0 on first delivery).
+     *
+     * TODO(impl): verify RetryCount is present on ALL event type envelopes,
+     * not just transaction events. wh-account-connected.txt does not show it
+     * in the response example but wh-transaction-payment-created.txt does.
+     * @see references/viva-docs/md/wh-transaction-payment-created.txt:255
+     */
+    readonly RetryCount?: number;
+    /**
+     * Delay in seconds between retries. Null on first delivery.
+     *
+     * @see references/viva-docs/md/wh-transaction-payment-created.txt:257
+     */
+    readonly RetryDelayInSeconds?: number | null;
+}
+/**
+ * Base shape for transaction event data (EventTypeId 1796, 1797, 1798).
+ *
+ * All three share the same flat structure. Differences:
+ * - 1796: StatusId is typically 'F' (Finished/captured)
+ * - 1797: StatusId is typically 'R' (Refunded); ParentId links to original
+ * - 1798: StatusId is typically 'E' (Error)
+ *
+ * Amount ambiguity: the docs show `Amount: decimal` in the description text
+ * (webhooks-for-payments.txt:483) but the createOrder request uses integer
+ * minor units. The sample payloads show integer values (Amount: 10, 1000).
+ *
+ * TODO(impl): verify Amount unit (minor int vs major decimal) against first
+ * real demo payment. Treat as minor units until confirmed otherwise.
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:344
+ *
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:158
+ */
+export interface TransactionEventData {
+    /** The TransactionId of the transaction. */
+    readonly TransactionId: TransactionId;
+    /** The OrderCode of the transaction. */
+    readonly OrderCode: OrderCode;
+    /**
+     * Status letter. See VivaStatusLetter in status.ts.
+     *
+     * @see references/viva-docs/md/wh-transaction-payment-created.txt:398
+     */
+    readonly StatusId: string;
+    /**
+     * Signed amount of the transaction. Represents total funds paid by the
+     * customer (includes TotalFee).
+     *
+     * TODO(impl): verify unit — docs say decimal, sample shows integer.
+     * Assuming minor units. Treat as number on wire, convert to bigint on ingest.
+     * @see references/viva-docs/md/wh-transaction-payment-created.txt:344
+     */
+    readonly Amount: number;
+    /**
+     * ISO 4217 numeric currency code string.
+     *
+     * @see references/viva-docs/md/wh-transaction-payment-created.txt:487
+     */
+    readonly CurrencyCode: CurrencyCode;
+    /** MerchantId of the merchant. Used for tenant routing. */
+    readonly MerchantId: string;
+    /**
+     * ConnectedAccountId (ISV schema). May be null if not ISV-scoped.
+     * Used for onboarding event tenant routing.
+     *
+     * @see references/viva-docs/md/wh-transaction-payment-created.txt:224
+     */
+    readonly ConnectedAccountId: string | null;
+    /** Parent TransactionId (if this is a reversal/refund). */
+    readonly ParentId: TransactionId | null;
+    /** ISO 8601 timestamp when the transaction occurred. */
+    readonly InsDate: string;
+    /** Transaction type numeric identifier (5 = CardCharge, 4 = Refund, etc.). */
+    readonly TransactionTypeId: number;
+    /** Customer email. May be masked. */
+    readonly Email: string | null;
+    /** Customer full name. */
+    readonly FullName: string | null;
+    /** Masked card number (e.g. "414746XXXXXX0133"). */
+    readonly CardNumber: string | null;
+    /**
+     * Card type: 0=Visa, 1=Mastercard, 2=Diners, 3=Amex, 4=Invalid,
+     * 5=Unknown, 6=Maestro, 7=Discover, 8=JCB.
+     *
+     * @see references/viva-docs/md/wh-transaction-payment-created.txt:770
+     */
+    readonly CardTypeId: number;
+    /** Merchant transaction reference. */
+    readonly MerchantTrns: string | null;
+    /** Customer transaction reference. */
+    readonly CustomerTrns: string | null;
+    /** Source code of the Merchant's payment source. */
+    readonly SourceCode: string;
+    /** Total fees (signed). */
+    readonly TotalFee: number;
+    /** Card expiration date in ISO 8601 format. */
+    readonly CardExpirationDate: string | null;
+    /** Two-letter ISO country code of the card-issuing country. */
+    readonly CardCountryCode: string | null;
+    /** Name of the card-issuing bank. */
+    readonly CardIssuingBank: string | null;
+    /**
+     * Internal event ID used for failure classification on 1798.
+     * The ResponseEventId indicates why a payment failed.
+     *
+     * @see references/viva-docs/md/wh-transaction-failed.txt:243
+     */
+    readonly ResponseEventId: number | null;
+    /** Order tags. */
+    readonly Tags: readonly string[];
+    /** Reseller ID if applicable. */
+    readonly ResellerId: string | null;
+    readonly ResellerCompanyName: string | null;
+    readonly ResellerSourceCode: string | null;
+    readonly ResellerSourceAddress: string | null;
+    readonly CompanyName: string;
+    readonly CompanyTitle: string;
+    readonly AuthorizationId: string;
+    readonly ReferenceNumber: number;
+    readonly ResponseCode: string | null;
+    /** Whether this is a Mail Order / Telephone Order transaction. */
+    readonly Moto: boolean;
+    readonly DualMessage: boolean;
+    readonly TipAmount: number;
+    readonly TotalInstallments: number;
+    readonly CurrentInstallment: number;
+    readonly ElectronicCommerceIndicator: string | null;
+    /** Digital wallet type ID (2=Apple Pay, 3=Google Pay, 4=Samsung Pay). */
+    readonly DigitalWalletId: number | null;
+    readonly BinId: number;
+    readonly IsDcc: boolean;
+    /** DCC conversion rate. */
+    readonly ConversionRate: number;
+    readonly OriginalAmount: number;
+    readonly OriginalCurrencyCode: CurrencyCode | null;
+    readonly OrderCulture: string;
+    readonly CardToken: string | null;
+    readonly CardUniqueReference: string | null;
+    readonly TargetPersonId: string | null;
+    readonly TargetWalletId: string | null;
+    readonly SourceName: string;
+    readonly Latitude: number | null;
+    readonly Longitude: number | null;
+    readonly BatchId: string | null;
+    readonly PanEntryMode: string;
+    readonly BankId: string;
+    readonly ChannelId: string;
+    readonly TerminalId: number;
+    readonly ProductId: string | null;
+    readonly Descriptor: string | null;
+    readonly Switching: boolean;
+    readonly Systemic: boolean;
+    readonly AcquirerApproved: boolean;
+    readonly LoyaltyTriggered: boolean;
+    readonly RedeemedAmount: number;
+    readonly SurchargeAmount: number | null;
+    readonly ClearanceDate: string | null;
+    readonly Ucaf: string | null;
+    readonly IsManualRefund: boolean;
+    readonly BillId: string | null;
+    readonly MerchantCategoryCode: number | null;
+    readonly ExternalTransactionId: string | null;
+    readonly RetrievalReferenceNumber: string | null;
+    readonly AssignedMerchantUsers: readonly string[];
+    readonly AssignedResellerUsers: readonly string[];
+    readonly CardProductCategoryId: number | null;
+    readonly CardProductAccountTypeId: number | null;
+    readonly OrderServiceId: number;
+    readonly ApplicationIdentifierTerminal: string | null;
+    readonly IntegrationId: number | null;
+    readonly PrimaryAccountNumberLast4Digits: string | null;
+    readonly ServiceId: number | null;
+    readonly ResellerSourceName: string | null;
+    readonly DccSessionId: string | null;
+    readonly DccMarkup: number | null;
+    readonly DccDifferenceOverEcb: number | null;
+}
+/**
+ * EventData for Transaction Payment Created (EventTypeId 1796).
+ * StatusId is typically 'F' (Finished/captured).
+ *
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:158
+ */
+export type TransactionPaymentCreatedEventData = TransactionEventData;
+/**
+ * EventData for Transaction Reversal Created (EventTypeId 1797).
+ * StatusId is typically 'R' (Refunded).
+ * ParentId references the original transaction.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:167
+ */
+export type TransactionReversalCreatedEventData = TransactionEventData;
+/**
+ * EventData for Transaction Failed (EventTypeId 1798).
+ * StatusId is typically 'E' (Error).
+ * ResponseEventId indicates the failure reason.
+ *
+ * @see references/viva-docs/md/wh-transaction-failed.txt:162
+ */
+export type TransactionFailedEventData = TransactionEventData;
+/**
+ * EventData for Order Updated (EventTypeId 4865).
+ *
+ * Sent when an order is cancelled via Smart Checkout's back button or the
+ * cancel-order API. The EventData shape may differ from transaction events.
+ *
+ * TODO(impl): verify exact EventData fields for 4865 Order Updated.
+ * The webhooks-for-payments.txt doc lists it but does not show a sample.
+ * wh-transaction-payment-created.txt and wh-transaction-failed.txt cover
+ * 1796/1798; no dedicated 4865 doc exists in the local mirror.
+ * @see references/viva-docs/md/webhooks-for-payments.txt:207
+ */
+export interface OrderUpdatedEventData {
+    /** The order code of the updated/cancelled order. */
+    readonly OrderCode: OrderCode;
+    /**
+     * The merchant ID for tenant routing.
+     * TODO(impl): confirm MerchantId is present on 4865 payload.
+     * @see references/viva-docs/md/webhooks-for-payments.txt:207
+     */
+    readonly MerchantId?: string;
+    /**
+     * Raw event data — preserved as unknown for forensics until shape confirmed.
+     * TODO(impl): replace with fully typed fields once 4865 sample payload obtained.
+     */
+    readonly raw?: unknown;
+}
+/**
+ * EventData for Account Connected (EventTypeId 8193).
+ *
+ * @see references/viva-docs/md/wh-account-connected.txt:150
+ */
+export interface AccountConnectedEventData {
+    /** ID of the created person/merchant. */
+    readonly PersonId: string;
+    /**
+     * The ID of the primary wallet created for the merchant.
+     * Stored as number (int64 on the wire); use BigInt if precision matters.
+     *
+     * @see references/viva-docs/md/wh-account-connected.txt:154
+     */
+    readonly WalletId: number;
+    /** ID of the ISV platform account. */
+    readonly PlatformPersonId: string;
+    /**
+     * Connected account ID (UUID). Use for tenant routing on onboarding events.
+     *
+     * @see references/viva-docs/md/wh-account-connected.txt:155
+     */
+    readonly ConnectedAccountId: string;
+}
+/**
+ * EventData for Account Verification Status Changed (EventTypeId 8194).
+ *
+ * @see references/viva-docs/md/wh-account-verif-status-changed.txt:152
+ */
+export interface AccountVerificationStatusChangedEventData {
+    /**
+     * True if the account is now verified.
+     *
+     * @see references/viva-docs/md/wh-account-verif-status-changed.txt:155
+     */
+    readonly Verified: boolean;
+    /** ID of the created person/merchant. */
+    readonly PersonId: string;
+    /** ID of the ISV platform account. */
+    readonly PlatformPersonId: string;
+    /**
+     * Connected account ID (UUID). Use for tenant routing on onboarding events.
+     *
+     * @see references/viva-docs/md/wh-account-verif-status-changed.txt:158
+     */
+    readonly ConnectedAccountId: string;
+}
+/**
+ * Discriminated union of all typed webhook envelopes for v1-scope event types.
+ * Switch on `EventTypeId` to narrow to the specific EventData type.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:141
+ */
+export type VivaWebhookEnvelope = WebhookEnvelope<TransactionPaymentCreatedEventData> & {
+    readonly EventTypeId: 1796;
+} | WebhookEnvelope<TransactionReversalCreatedEventData> & {
+    readonly EventTypeId: 1797;
+} | WebhookEnvelope<TransactionFailedEventData> & {
+    readonly EventTypeId: 1798;
+} | WebhookEnvelope<OrderUpdatedEventData> & {
+    readonly EventTypeId: 4865;
+} | WebhookEnvelope<AccountConnectedEventData> & {
+    readonly EventTypeId: 8193;
+} | WebhookEnvelope<AccountVerificationStatusChangedEventData> & {
+    readonly EventTypeId: 8194;
+};
+//# sourceMappingURL=webhook-events.d.ts.map

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

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

package/dist/types/webhook-events.js

@@ -0,0 +1,76 @@
+/**
+ * Webhook event types and payloads for the Viva Wallet ISV integration.
+ *
+ * Covers: WebhookEnvelope<T> generic, EVENT_TYPES const object, and typed
+ * EventData payloads for v1-scope event types:
+ *   1796 — Transaction Payment Created
+ *   1797 — Transaction Reversal Created
+ *   1798 — Transaction Failed
+ *   4865 — Order Updated (cancellation)
+ *   8193 — Account Connected
+ *   8194 — Account Verification Status Changed
+ *
+ * Event 7936 (Sale Transactions) is NOT in v1 scope per plan A8.
+ * HMAC verification only applies to 7936; not implemented in v1.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:141
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:158
+ * @see references/viva-docs/md/wh-transaction-failed.txt:162
+ * @see references/viva-docs/md/wh-account-connected.txt:150
+ * @see references/viva-docs/md/wh-account-verif-status-changed.txt:152
+ */
+// ---------------------------------------------------------------------------
+// EventTypeId const object (not a TypeScript enum)
+// ---------------------------------------------------------------------------
+/**
+ * v1-scope Viva Webhook event type identifiers.
+ *
+ * Defined as `as const` object per requirement 4 — NOT a TypeScript enum.
+ * This avoids TypeScript enum pitfalls (numeric reverse-mapping, etc.).
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:141
+ */
+export const EVENT_TYPES = {
+    /** A customer payment has been successful. */
+    TRANSACTION_PAYMENT_CREATED: 1796,
+    /** A customer refund has been successfully actioned. */
+    TRANSACTION_REVERSAL_CREATED: 1797,
+    /** A customer payment failed. */
+    TRANSACTION_FAILED: 1798,
+    /** An order was cancelled (API or Smart Checkout back button). */
+    ORDER_UPDATED: 4865,
+    /** An account is successfully connected to the ISV account. */
+    ACCOUNT_CONNECTED: 8193,
+    /** Verification status of a connected account changed. */
+    ACCOUNT_VERIFICATION_STATUS_CHANGED: 8194,
+};
+/**
+ * Deferred event type IDs — documented for future implementation.
+ * NOT in v1 scope per plan A8 and the narrowed event-type set.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:141
+ */
+export const DEFERRED_EVENT_TYPES = {
+    /** Commission payment withdrawn by Viva. Post-v1. */
+    TRANSACTION_PRICE_CALCULATED: 1799,
+    /** ECR integration only. Post-v1. */
+    TRANSACTION_POS_ECR_SESSION_CREATED: 1802,
+    /** ECR integration only. Post-v1. */
+    TRANSACTION_POS_ECR_SESSION_FAILED: 1803,
+    /** Wallet account balance change. Post-v1. */
+    ACCOUNT_TRANSACTION_CREATED: 2054,
+    /** Bank transfer created. Post-v1. */
+    COMMAND_BANK_TRANSFER_CREATED: 768,
+    /** Bank transfer executed. Post-v1. */
+    COMMAND_BANK_TRANSFER_EXECUTED: 769,
+    /**
+     * Sale transactions report file available. NOT in v1 — HMAC-signed webhook
+     * distinct from transaction events. Re-add in v1.1 if needed.
+     *
+     * @see references/viva-docs/md/wh-sale-transactions.txt:118
+     */
+    SALE_TRANSACTIONS: 7936,
+    /** Marketplace-only: a transfer has been made. Post-v1. */
+    TRANSFER_CREATED: 8448,
+};
+//# sourceMappingURL=webhook-events.js.map

package/dist/types/webhook-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-events.js","sourceRoot":"","sources":["../../src/types/webhook-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,8EAA8E;AAC9E,mDAAmD;AACnD,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,8CAA8C;IAC9C,2BAA2B,EAAE,IAAI;IACjC,wDAAwD;IACxD,4BAA4B,EAAE,IAAI;IAClC,iCAAiC;IACjC,kBAAkB,EAAE,IAAI;IACxB,kEAAkE;IAClE,aAAa,EAAE,IAAI;IACnB,+DAA+D;IAC/D,iBAAiB,EAAE,IAAI;IACvB,0DAA0D;IAC1D,mCAAmC,EAAE,IAAI;CACjC,CAAC;AAOX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,qDAAqD;IACrD,4BAA4B,EAAE,IAAI;IAClC,qCAAqC;IACrC,mCAAmC,EAAE,IAAI;IACzC,qCAAqC;IACrC,kCAAkC,EAAE,IAAI;IACxC,8CAA8C;IAC9C,2BAA2B,EAAE,IAAI;IACjC,sCAAsC;IACtC,6BAA6B,EAAE,GAAG;IAClC,uCAAuC;IACvC,8BAA8B,EAAE,GAAG;IACnC;;;;;OAKG;IACH,iBAAiB,EAAE,IAAI;IACvB,2DAA2D;IAC3D,gBAAgB,EAAE,IAAI;CACd,CAAC"}

package/dist/webhooks/challenge-response.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Viva Wallet webhook challenge-response handler.
+ *
+ * When Viva verifies a webhook URL at registration time it sends a GET request.
+ * The endpoint must respond with `{"Key": "<webhook_verification_key>"}`.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:311
+ */
+/**
+ * Returns the GET-request response body for Viva's URL verification challenge.
+ *
+ * @param webhookVerificationKey  The webhook verification key obtained from
+ *   Viva's `GET /api/messages/config/token` endpoint. Must be non-empty.
+ *
+ * @throws VivaWebhookError when the key is empty or whitespace-only.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:362
+ *
+ * @example
+ * // Route handler (framework-agnostic pseudocode):
+ * if (req.method === 'GET') {
+ *   return res.json(buildChallengeResponse(env.VIVA_WEBHOOK_KEY));
+ * }
+ */
+export declare function buildChallengeResponse(webhookVerificationKey: string): {
+    Key: string;
+};
+//# sourceMappingURL=challenge-response.d.ts.map

package/dist/webhooks/challenge-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge-response.d.ts","sourceRoot":"","sources":["../../src/webhooks/challenge-response.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,sBAAsB,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAUtF"}

package/dist/webhooks/challenge-response.js

@@ -0,0 +1,35 @@
+/**
+ * Viva Wallet webhook challenge-response handler.
+ *
+ * When Viva verifies a webhook URL at registration time it sends a GET request.
+ * The endpoint must respond with `{"Key": "<webhook_verification_key>"}`.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:311
+ */
+import { VivaWebhookError } from '../errors/index.js';
+/**
+ * Returns the GET-request response body for Viva's URL verification challenge.
+ *
+ * @param webhookVerificationKey  The webhook verification key obtained from
+ *   Viva's `GET /api/messages/config/token` endpoint. Must be non-empty.
+ *
+ * @throws VivaWebhookError when the key is empty or whitespace-only.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:362
+ *
+ * @example
+ * // Route handler (framework-agnostic pseudocode):
+ * if (req.method === 'GET') {
+ *   return res.json(buildChallengeResponse(env.VIVA_WEBHOOK_KEY));
+ * }
+ */
+export function buildChallengeResponse(webhookVerificationKey) {
+    if (!webhookVerificationKey || webhookVerificationKey.trim().length === 0) {
+        throw new VivaWebhookError({
+            message: 'webhookVerificationKey must be a non-empty string. ' +
+                'Obtain it from GET /api/messages/config/token and set VIVA_WEBHOOK_KEY.',
+        });
+    }
+    return { Key: webhookVerificationKey };
+}
+//# sourceMappingURL=challenge-response.js.map

package/dist/webhooks/challenge-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge-response.js","sourceRoot":"","sources":["../../src/webhooks/challenge-response.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CAAC,sBAA8B;IACnE,IAAI,CAAC,sBAAsB,IAAI,sBAAsB,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1E,MAAM,IAAI,gBAAgB,CAAC;YACzB,OAAO,EACL,qDAAqD;gBACrD,yEAAyE;SAC5E,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,sBAAsB,EAAE,CAAC;AACzC,CAAC"}

package/dist/webhooks/event-types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime helpers for Viva webhook event type IDs.
+ *
+ * Re-exports EVENT_TYPES and VivaEventTypeId from the types package, and
+ * provides runtime type-guard helpers for routing webhook payloads.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:141
+ */
+export { EVENT_TYPES, type VivaEventTypeId } from '../types/webhook-events.js';
+/**
+ * Returns `true` for event types that carry a transaction payload and require
+ * MerchantId-based tenant resolution.
+ *
+ * v1-scope transaction events:
+ *   1796 — Transaction Payment Created
+ *   1797 — Transaction Reversal Created
+ *   1798 — Transaction Failed
+ *   4865 — Order Updated (cancellation)
+ *   7936 — Sale Transactions (HMAC-signed, deferred from v1 core but type-guard kept)
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:141
+ */
+export declare function isTransactionEvent(id: number): id is 1796 | 1797 | 1798 | 4865 | 7936;
+/**
+ * Returns `true` for event types that carry an onboarding payload and require
+ * ConnectedAccountId-based tenant resolution.
+ *
+ * v1-scope onboarding events:
+ *   8193 — Account Connected
+ *   8194 — Account Verification Status Changed
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:224
+ */
+export declare function isOnboardingEvent(id: number): id is 8193 | 8194;
+/**
+ * All v1-scope event IDs as a frozen array.
+ *
+ * Used by `viva:register-webhooks` CLI to enumerate the required registrations
+ * and by the route handler to reject unknown event types.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:141
+ */
+export declare const V1_EVENT_TYPE_IDS: readonly (1796 | 1797 | 1798 | 4865 | 8193 | 8194)[];
+//# sourceMappingURL=event-types.d.ts.map

package/dist/webhooks/event-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-types.d.ts","sourceRoot":"","sources":["../../src/webhooks/event-types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE/E;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAErF;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,IAAI,GAAG,IAAI,CAE/D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,EAEvE,CAAC"}