@samva/webhooks 0.13.0 → 0.15.0

package/README.md

@@ -4,14 +4,17 @@ Verify signed Samva webhook deliveries in Node.js, Bun, Cloudflare Workers, and
 Crypto-compatible runtimes.
 
 ```ts
-import { verifyRequest } from "@samva/webhooks";
+import { isKnownEvent, verifyRequest } from "@samva/webhooks";
 
 const verified = await verifyRequest(request, process.env.SAMVA_WEBHOOK_SECRET!);
+if (isKnownEvent(verified.event) && verified.event.type === "message.bounced") {
+  await suppressRecipient(verified.event.data.recipient, verified.event.data.occurredAt);
+}
 await persistAndHandleOnce(verified.id, verified.event);
 ```
 
 Verification reads the exact request body, validates the Standard Webhooks signature and replay
-window, and returns `{ id, event }`. `verified.id` matches the `webhook-id` header. Preserve the raw
+window and the event-specific payload, and returns `{ id, event }`. `verified.id` matches the `webhook-id` header. Preserve the raw
 request body and keep the signing secret on the server.
 
 Effect applications can use the optional Effect entrypoint:
@@ -27,3 +30,21 @@ const program = Effect.gen(function* () {
 ```
 
 Install the `effect` version this package lists in `peerDependencies` when using that entrypoint.
+
+`VerifiedWebhook.event` is a `WebhookEvent`: a known `SamvaWebhookEvent` or an
+`UnknownWebhookEvent` with `type: string` and `data: unknown`. Call `isKnownEvent(event)` before
+branching on `event.type` to narrow known payloads. Per-event types such as `MessageBouncedPayload`
+and `ContactUnsubscribedPayload` are exported from both entrypoints.
+
+Signature verification is the authenticity gate. Signed new event types pass through as untyped
+events; extra envelope and payload fields are accepted and preserved. Only malformed envelopes or
+invalid payloads for known event types fail with `MalformedWebhookPayloadError`. Update the package
+to gain types for new events. Bounce and complaint events publish once per affected address, each
+with its own `webhook-id`; deduplicate using that ID rather than `messageId`.
+
+For separate decoding, import `MessageBouncedEventSchema` or `SamvaWebhookEventSchema` from
+`@samva/webhooks/schemas` (or the Effect entrypoint) and use `Schema.decodeUnknownSync`.
+`WebhookEventJsonSchemas` exports the same wire contracts for JSON Schema validators.
+
+Signing secrets are `whsec_` followed by Base64-encoded secret bytes. Copy the entire secret from
+Samva; the suffix is Base64, not hex or Base64url.

package/dist/decoder.gen.d.ts

@@ -0,0 +1,4 @@
+import type { SamvaWebhookEvent, WebhookEvent } from "./types.gen.js";
+/** Narrow an event to a structurally valid payload known to this package. */
+export declare const isKnownEvent: (value: WebhookEvent) => value is SamvaWebhookEvent;
+export declare const validateEvent: (value: unknown) => value is WebhookEvent;

package/dist/effect.d.ts

@@ -38,6 +38,9 @@ export declare const verify: (options: VerifyOptions) => Effect.Effect<VerifiedW
 export declare const verifyRequest: (request: Request, secret: string, options?: {
     readonly toleranceSeconds?: number | undefined;
 } | undefined) => Effect.Effect<VerifiedWebhook, AnyWebhookVerificationError, never>;
-export { DEFAULT_TOLERANCE_SECONDS, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, generateWebhookSecret, signWebhook, } from "./protocol.js";
+export { DEFAULT_TOLERANCE_SECONDS, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, isKnownEvent, generateWebhookSecret, signWebhook, } from "./protocol.js";
 export type { AnyWebhookVerificationError, SamvaWebhookEvent, VerifiedWebhook, WebhookHeaderName, } from "./protocol.js";
 export { InvalidWebhookHeadersError, InvalidWebhookSecretError, MalformedWebhookPayloadError, WebhookCryptoError, WebhookSignatureError, WebhookTimestampError, WebhookVerificationError, } from "./protocol.js";
+export type * from "./types.gen.js";
+export { WebhookEventJsonSchemas } from "./json-schemas.gen.js";
+export * from "./schemas.gen.js";

package/dist/effect.js

@@ -1,4 +1,6 @@
-import { _ as WebhookTimestampError, c as signWebhook, f as InvalidWebhookHeadersError, g as WebhookSignatureError, h as WebhookCryptoError, i as WEBHOOK_TIMESTAMP_HEADER, l as verifyWebhookAt, m as MalformedWebhookPayloadError, n as WEBHOOK_ID_HEADER, o as generateWebhookSecret, p as InvalidWebhookSecretError, r as WEBHOOK_SIGNATURE_HEADER, t as DEFAULT_TOLERANCE_SECONDS, v as WebhookVerificationError } from "./protocol-BGKUmvlI.js";
+import { _ as WebhookTimestampError, c as signWebhook, f as InvalidWebhookHeadersError, g as WebhookSignatureError, h as WebhookCryptoError, i as WEBHOOK_TIMESTAMP_HEADER, l as verifyWebhookAt, m as MalformedWebhookPayloadError, n as WEBHOOK_ID_HEADER, o as generateWebhookSecret, p as InvalidWebhookSecretError, r as WEBHOOK_SIGNATURE_HEADER, t as DEFAULT_TOLERANCE_SECONDS, v as WebhookVerificationError, y as isKnownEvent } from "./protocol-CLrYczjc.js";
+import { t as WebhookEventJsonSchemas } from "./json-schemas.gen-eya_ZDps.js";
+import { ContactCreatedEventSchema, ContactDeletedEventSchema, ContactResubscribedEventSchema, ContactSubscribedEventSchema, ContactUnsubscribedEventSchema, ContactUpdatedEventSchema, ConversationArchivedEventSchema, ConversationCreatedEventSchema, ConversationUpdatedEventSchema, DomainUpdatedEventSchema, DomainWarmingUpdatedEventSchema, MailboxActionPendingApprovalEventSchema, MailboxMessageDiscardedEventSchema, MailboxMessageQuarantinedEventSchema, MailboxMessageReceivedEventSchema, MailboxMessageReleasedEventSchema, MailboxMessageSentEventSchema, MessageBouncedEventSchema, MessageClickedEventSchema, MessageComplainedEventSchema, MessageDeliveredEventSchema, MessageFailedEventSchema, MessageOpenedEventSchema, MessageReadEventSchema, MessageReceivedEventSchema, MessageSentEventSchema, SamvaWebhookEventSchema, WebhookCreatedEventSchema, WebhookDeletedEventSchema, WebhookTestEventSchema, WebhookUpdatedEventSchema } from "./schemas.gen.js";
 import { Clock, Effect } from "effect";
 //#region src/effect.ts
 /**
@@ -73,6 +75,6 @@ const verifyRequest = Effect.fn("Webhooks.verifyRequest")(function* (request, se
 	});
 });
 //#endregion
-export { DEFAULT_TOLERANCE_SECONDS, InvalidWebhookHeadersError, InvalidWebhookSecretError, MalformedWebhookPayloadError, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, WebhookCryptoError, WebhookSignatureError, WebhookTimestampError, WebhookVerificationError, generateWebhookSecret, signWebhook, verify, verifyRequest };
+export { ContactCreatedEventSchema, ContactDeletedEventSchema, ContactResubscribedEventSchema, ContactSubscribedEventSchema, ContactUnsubscribedEventSchema, ContactUpdatedEventSchema, ConversationArchivedEventSchema, ConversationCreatedEventSchema, ConversationUpdatedEventSchema, DEFAULT_TOLERANCE_SECONDS, DomainUpdatedEventSchema, DomainWarmingUpdatedEventSchema, InvalidWebhookHeadersError, InvalidWebhookSecretError, MailboxActionPendingApprovalEventSchema, MailboxMessageDiscardedEventSchema, MailboxMessageQuarantinedEventSchema, MailboxMessageReceivedEventSchema, MailboxMessageReleasedEventSchema, MailboxMessageSentEventSchema, MalformedWebhookPayloadError, MessageBouncedEventSchema, MessageClickedEventSchema, MessageComplainedEventSchema, MessageDeliveredEventSchema, MessageFailedEventSchema, MessageOpenedEventSchema, MessageReadEventSchema, MessageReceivedEventSchema, MessageSentEventSchema, SamvaWebhookEventSchema, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, WebhookCreatedEventSchema, WebhookCryptoError, WebhookDeletedEventSchema, WebhookEventJsonSchemas, WebhookSignatureError, WebhookTestEventSchema, WebhookTimestampError, WebhookUpdatedEventSchema, WebhookVerificationError, generateWebhookSecret, isKnownEvent, signWebhook, verify, verifyRequest };
 
 //# sourceMappingURL=effect.js.map