feat: add the webhooks namespace and signature verification

javascript/package.json

@@ -32,6 +32,7 @@
   ],
   "license": "MIT",
   "devDependencies": {
+    "@types/node": "^22.20.1",
     "oxlint": "^1.77.0",
     "tsup": "^8.0.0",
     "typescript": "^7.0.2",

javascript/src/client.ts

@@ -2,6 +2,7 @@
 
 import { resolveConfig, type CosmonerConfig, type ResolvedConfig } from "./config";
 import { EmailService } from "./services/email";
+import { WebhooksService } from "./services/webhooks";
 import { Transport } from "./transport";
 
 /**
@@ -27,6 +28,7 @@ export class Cosmoner {
   private readonly transport: Transport;
 
   readonly email: EmailService;
+  readonly webhooks: WebhooksService;
 
   constructor(config: CosmonerConfig) {
     this.config = resolveConfig(config);
@@ -39,5 +41,6 @@ export class Cosmoner {
 
     this.transport = new Transport(this.config);
     this.email = new EmailService(this.transport, this.config);
+    this.webhooks = new WebhooksService(this.transport, this.config);
   }
 }

javascript/src/errors.ts

@@ -114,6 +114,20 @@ export class ServerError extends CosmonerError {
   }
 }
 
+/**
+ * A received webhook could not be verified against its signing secret.
+ *
+ * Unlike the rest of the hierarchy this never comes from an API response — it
+ * is raised locally while checking an inbound request, so it carries no
+ * meaningful HTTP status.
+ */
+export class WebhookSignatureError extends CosmonerError {
+  constructor(message: string) {
+    super(0, "WEBHOOK_SIGNATURE_INVALID", message);
+    this.name = "WebhookSignatureError";
+  }
+}
+
 /** Shape of the API's error envelope. */
 interface ErrorEnvelope {
   success?: false;

javascript/src/index.ts

@@ -18,12 +18,47 @@ export {
   RateLimitError,
   ServerError,
   ValidationError,
+  WebhookSignatureError,
 } from "./errors";
 export {
   EmailService,
   type SendEmailParams,
   type SendEmailResponse,
 } from "./services/email";
+export {
+  WEBHOOK_EVENT_TYPES,
+  WebhooksService,
+  type CreateWebhookEndpointParams,
+  type CreateWebhookEndpointResponse,
+  type DeleteWebhookEndpointResponse,
+  type GetWebhookEndpointResponse,
+  type ListDeliveriesParams,
+  type ListWebhookDeliveriesResponse,
+  type ListWebhookEndpointsResponse,
+  type ReplayWebhookDeliveryResponse,
+  type ResumeWebhookEndpointResponse,
+  type RotateWebhookSecretResponse,
+  type TestWebhookEndpointResponse,
+  type UpdateWebhookEndpointParams,
+  type UpdateWebhookEndpointResponse,
+  type WebhookDelivery,
+  type WebhookDeliveryStatus,
+  type WebhookDisabledReason,
+  type WebhookEndpoint,
+  type WebhookEndpointStats,
+  type WebhookEndpointWithSecret,
+  type WebhookEventType,
+} from "./services/webhooks";
+export {
+  constructEvent,
+  DEFAULT_TOLERANCE_SECONDS,
+  DELIVERY_ID_HEADER,
+  EVENT_TYPE_HEADER,
+  SIGNATURE_HEADER,
+  verifyWebhookSignature,
+  type VerifyWebhookParams,
+  type WebhookEvent,
+} from "./webhooks/signature";
 export { VERSION } from "./version";
 
 import { Cosmoner } from "./client";