@wassist/sdk 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 
-## 0.1.0 (Unreleased)
+## 0.1.1
+
+- **Fix**: `WassistEvent` is now a clean discriminated union — `switch (event.event)` correctly narrows every known case to its specific event type, so fields like `event.message.body` and `event.conversationId` are typed inside the branch (previously they collapsed to `unknown` because the catch-all `WassistEventBase<string> & Record<string, unknown>` member was part of the union). The catch-all has been split out into a separate, opt-in `UnrecognizedWassistEvent` type for forward-compat handling of future event names.
+- Runnable [examples](./examples) for a quickstart agent setup script, a Next.js / Vercel webhook receiver, and a Cloudflare Workers webhook receiver — each with a one-click deploy button where applicable.
+
+## 0.1.0
 
 Initial release.
 

package/README.md

@@ -48,6 +48,16 @@ for await (const c of wassist.conversations.list()) {
 
 Get your API key at [wassist.app/settings](https://wassist.app/settings).
 
+## Examples
+
+Runnable, self-contained examples live in [`examples/`](https://github.com/wassist/sdk/tree/main/examples). Each one is its own mini-package — `cd` in, install, and go.
+
+| Example | What it shows | Deploy |
+|---------|---------------|--------|
+| [`quickstart-setup-agent`](https://github.com/wassist/sdk/tree/main/examples/quickstart-setup-agent) | One-shot script: create an agent, configure prompts and icebreakers, optionally connect a phone number. | — |
+| [`webhook-receiver-vercel`](https://github.com/wassist/sdk/tree/main/examples/webhook-receiver-vercel) | Next.js App Router route that verifies Wassist webhooks and echoes inbound messages. | [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwassist%2Fsdk&root-directory=examples%2Fwebhook-receiver-vercel&project-name=wassist-webhook-vercel&env=WASSIST_API_KEY,WASSIST_WEBHOOK_SECRET) |
+| [`webhook-receiver-cloudflare`](https://github.com/wassist/sdk/tree/main/examples/webhook-receiver-cloudflare) | Cloudflare Worker that verifies Wassist webhooks via Web Crypto and echoes inbound messages. | [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/wassist/sdk/tree/main/examples/webhook-receiver-cloudflare&secrets=WASSIST_API_KEY,WASSIST_WEBHOOK_SECRET) |
+
 ## Configuration
 
 ```ts

package/dist/index.d.cts

@@ -1399,13 +1399,34 @@ interface TestPingEvent extends WassistEventBase<'test.ping'> {
     message: string;
 }
 /**
- * Discriminated union of every documented Wassist webhook event.
+ * Discriminated union of every documented Wassist webhook event. Designed
+ * for clean narrowing in a `switch (event.event)`:
  *
- * Unknown future events are still typed (as the `unknown` fallback) so a
- * runtime call to {@link Wassist.webhooks.constructEvent} never throws on
- * an unrecognized `event` name.
+ * ```ts
+ * switch (event.event) {
+ *   case 'message.received':       event.message.body;     // typed
+ *   case 'subscription.activated': event.webhookId;        // typed
+ * }
+ * ```
+ *
+ * For forward-compatibility with new event types Wassist may ship before
+ * you upgrade the SDK, see {@link UnrecognizedWassistEvent}.
+ */
+type WassistEvent = MessageReceivedEvent | SubscriptionActivatedEvent | SubscriptionRevokedEvent | TestPingEvent;
+/**
+ * Catch-all shape for events whose name {@link WassistEvent} doesn't yet
+ * know about. `constructEvent` never throws on an unrecognized event name
+ * at runtime — cast to this type when you need to inspect a future event:
+ *
+ * ```ts
+ * const event = Wassist.webhooks.constructEvent(...);
+ * if ((event.event as string).startsWith('beta.')) {
+ *   const unknown = event as UnrecognizedWassistEvent;
+ *   console.log(unknown.event, unknown.timestamp);
+ * }
+ * ```
  */
-type WassistEvent = MessageReceivedEvent | SubscriptionActivatedEvent | SubscriptionRevokedEvent | TestPingEvent | (WassistEventBase<string> & Record<string, unknown>);
+type UnrecognizedWassistEvent = WassistEventBase<string> & Record<string, unknown>;
 
 /**
  * Webhook signature verification.
@@ -1623,4 +1644,4 @@ declare class WassistSignatureVerificationError extends WassistError {
  */
 declare const SDK_VERSION = "0.1.0";
 
-export { type AddNumberInput, type Agent, type AgentCreditSettings, type AgentCreditSettingsInput, type AgentDocument, type AgentHandoffTool, type AgentHandoffToolInput, type AgentImageGenerateTool, type AgentImageGenerateToolInput, type AgentMcpConfig, type AgentMcpConfigInput, type AgentMemoryKey, type AgentMemoryKeyInput, type AgentOutboundTrigger, type AgentOutboundTriggerInput, type AgentPaywallConfig, type AgentPaywallConfigInput, type AgentTool, type AgentToolInput, type AgentWakeUpConfig, type AgentWakeUpConfigInput, type AgentWebsiteTool, type AgentWebsiteToolInput, type AgentWhatsAppPhoneNumber, AgentsResource, AutoPaginatedList, type AvailableNumber, type AvailableNumbersResponse, type CTAButtonMessage, type ConnectAgentInput, type Conversation, type ConversationContact, type ConversationLastMessage, ConversationsResource, type CreateAgentInput, type CreateBYOAAgentInput, type CreateConversationInput, type CreateConversationMessageInput, type CreateWhatsAppLinkSessionInput, type CreateWhatsAppTemplateInput, type FetchLike, type FileInfo, type ISODateTime, type ImageInfo, type ImageMessage, type ListConversationsParams, type ListSelectionMessage, type Message, type MessageReceivedEvent, type MessageReceivedMessage, type MessageRole, type MessageStatus, type MessageType, MessagesResource, type Page, type PageParams, type PaginatedResponse, type PhoneNumber, type PhoneNumberBusinessProfile, type PhoneNumberRoutingMode, type PhoneNumberString, PhoneNumbersResource, type PromptAgentInput, type PublicUser, type PublishWhatsAppTemplateInput, type QuickReplyMessage, type RequestOptions, SDK_VERSION, type SendMessageCtaImageInput, type SendMessageCtaInput, type SendMessageInput, type SendMessageTemplateInput, type SendMessageTextInput, type SendUnifiedMessageButtonInput, type SendUnifiedMessageInput, type SendUnifiedMessageMediaInput, type SubscribeConversationInput, type SubscribePhoneNumberInput, type SubscriptionActivatedEvent, type SubscriptionRevokedEvent, type TemplateMessage, type TestPingEvent, type TextMessage, type UUID, type UnifiedMessage, type UnifiedMessageButton, type UnifiedMessageButtonType, type UnifiedMessageMedia, type UnpublishWhatsAppTemplateInput, type UnsubscribePhoneNumberInput, type UpdateAgentInput, type UpdateWhatsAppTemplateInput, Wassist, WassistAPIError, WassistAuthenticationError, type WassistClientConfig, WassistConflictError, WassistConnectionError, WassistError, type WassistErrorOptions, type WassistEvent, type WassistEventBase, WassistInvalidRequestError, WassistNotFoundError, WassistPermissionError, WassistRateLimitError, WassistSignatureVerificationError, WassistTimeoutError, Webhooks, type WhatsAppAccount, type WhatsAppAccountPhoneNumber, WhatsAppAccountsResource, type WhatsAppLinkSession, type WhatsAppLinkSessionStatus, WhatsAppLinkSessionsResource, type WhatsAppTemplate, type WhatsAppTemplateAccountLink, type WhatsAppTemplateButton, type WhatsAppTemplateButtonType, type WhatsAppTemplateCategory, type WhatsAppTemplateComponent, type WhatsAppTemplateComponentExample, type WhatsAppTemplateNamedParam, type WhatsAppTemplateParameterFormat, type WhatsAppTemplatePublishResult, type WhatsAppTemplateQuality, type WhatsAppTemplateStatus, type WhatsAppTemplateUnpublishResult, type WhatsAppTemplateWithPublishResults, WhatsAppTemplatesResource };
+export { type AddNumberInput, type Agent, type AgentCreditSettings, type AgentCreditSettingsInput, type AgentDocument, type AgentHandoffTool, type AgentHandoffToolInput, type AgentImageGenerateTool, type AgentImageGenerateToolInput, type AgentMcpConfig, type AgentMcpConfigInput, type AgentMemoryKey, type AgentMemoryKeyInput, type AgentOutboundTrigger, type AgentOutboundTriggerInput, type AgentPaywallConfig, type AgentPaywallConfigInput, type AgentTool, type AgentToolInput, type AgentWakeUpConfig, type AgentWakeUpConfigInput, type AgentWebsiteTool, type AgentWebsiteToolInput, type AgentWhatsAppPhoneNumber, AgentsResource, AutoPaginatedList, type AvailableNumber, type AvailableNumbersResponse, type CTAButtonMessage, type ConnectAgentInput, type Conversation, type ConversationContact, type ConversationLastMessage, ConversationsResource, type CreateAgentInput, type CreateBYOAAgentInput, type CreateConversationInput, type CreateConversationMessageInput, type CreateWhatsAppLinkSessionInput, type CreateWhatsAppTemplateInput, type FetchLike, type FileInfo, type ISODateTime, type ImageInfo, type ImageMessage, type ListConversationsParams, type ListSelectionMessage, type Message, type MessageReceivedEvent, type MessageReceivedMessage, type MessageRole, type MessageStatus, type MessageType, MessagesResource, type Page, type PageParams, type PaginatedResponse, type PhoneNumber, type PhoneNumberBusinessProfile, type PhoneNumberRoutingMode, type PhoneNumberString, PhoneNumbersResource, type PromptAgentInput, type PublicUser, type PublishWhatsAppTemplateInput, type QuickReplyMessage, type RequestOptions, SDK_VERSION, type SendMessageCtaImageInput, type SendMessageCtaInput, type SendMessageInput, type SendMessageTemplateInput, type SendMessageTextInput, type SendUnifiedMessageButtonInput, type SendUnifiedMessageInput, type SendUnifiedMessageMediaInput, type SubscribeConversationInput, type SubscribePhoneNumberInput, type SubscriptionActivatedEvent, type SubscriptionRevokedEvent, type TemplateMessage, type TestPingEvent, type TextMessage, type UUID, type UnifiedMessage, type UnifiedMessageButton, type UnifiedMessageButtonType, type UnifiedMessageMedia, type UnpublishWhatsAppTemplateInput, type UnrecognizedWassistEvent, type UnsubscribePhoneNumberInput, type UpdateAgentInput, type UpdateWhatsAppTemplateInput, Wassist, WassistAPIError, WassistAuthenticationError, type WassistClientConfig, WassistConflictError, WassistConnectionError, WassistError, type WassistErrorOptions, type WassistEvent, type WassistEventBase, WassistInvalidRequestError, WassistNotFoundError, WassistPermissionError, WassistRateLimitError, WassistSignatureVerificationError, WassistTimeoutError, Webhooks, type WhatsAppAccount, type WhatsAppAccountPhoneNumber, WhatsAppAccountsResource, type WhatsAppLinkSession, type WhatsAppLinkSessionStatus, WhatsAppLinkSessionsResource, type WhatsAppTemplate, type WhatsAppTemplateAccountLink, type WhatsAppTemplateButton, type WhatsAppTemplateButtonType, type WhatsAppTemplateCategory, type WhatsAppTemplateComponent, type WhatsAppTemplateComponentExample, type WhatsAppTemplateNamedParam, type WhatsAppTemplateParameterFormat, type WhatsAppTemplatePublishResult, type WhatsAppTemplateQuality, type WhatsAppTemplateStatus, type WhatsAppTemplateUnpublishResult, type WhatsAppTemplateWithPublishResults, WhatsAppTemplatesResource };

package/dist/index.d.ts

@@ -1399,13 +1399,34 @@ interface TestPingEvent extends WassistEventBase<'test.ping'> {
     message: string;
 }
 /**
- * Discriminated union of every documented Wassist webhook event.
+ * Discriminated union of every documented Wassist webhook event. Designed
+ * for clean narrowing in a `switch (event.event)`:
  *
- * Unknown future events are still typed (as the `unknown` fallback) so a
- * runtime call to {@link Wassist.webhooks.constructEvent} never throws on
- * an unrecognized `event` name.
+ * ```ts
+ * switch (event.event) {
+ *   case 'message.received':       event.message.body;     // typed
+ *   case 'subscription.activated': event.webhookId;        // typed
+ * }
+ * ```
+ *
+ * For forward-compatibility with new event types Wassist may ship before
+ * you upgrade the SDK, see {@link UnrecognizedWassistEvent}.
+ */
+type WassistEvent = MessageReceivedEvent | SubscriptionActivatedEvent | SubscriptionRevokedEvent | TestPingEvent;
+/**
+ * Catch-all shape for events whose name {@link WassistEvent} doesn't yet
+ * know about. `constructEvent` never throws on an unrecognized event name
+ * at runtime — cast to this type when you need to inspect a future event:
+ *
+ * ```ts
+ * const event = Wassist.webhooks.constructEvent(...);
+ * if ((event.event as string).startsWith('beta.')) {
+ *   const unknown = event as UnrecognizedWassistEvent;
+ *   console.log(unknown.event, unknown.timestamp);
+ * }
+ * ```
  */
-type WassistEvent = MessageReceivedEvent | SubscriptionActivatedEvent | SubscriptionRevokedEvent | TestPingEvent | (WassistEventBase<string> & Record<string, unknown>);
+type UnrecognizedWassistEvent = WassistEventBase<string> & Record<string, unknown>;
 
 /**
  * Webhook signature verification.
@@ -1623,4 +1644,4 @@ declare class WassistSignatureVerificationError extends WassistError {
  */
 declare const SDK_VERSION = "0.1.0";
 
-export { type AddNumberInput, type Agent, type AgentCreditSettings, type AgentCreditSettingsInput, type AgentDocument, type AgentHandoffTool, type AgentHandoffToolInput, type AgentImageGenerateTool, type AgentImageGenerateToolInput, type AgentMcpConfig, type AgentMcpConfigInput, type AgentMemoryKey, type AgentMemoryKeyInput, type AgentOutboundTrigger, type AgentOutboundTriggerInput, type AgentPaywallConfig, type AgentPaywallConfigInput, type AgentTool, type AgentToolInput, type AgentWakeUpConfig, type AgentWakeUpConfigInput, type AgentWebsiteTool, type AgentWebsiteToolInput, type AgentWhatsAppPhoneNumber, AgentsResource, AutoPaginatedList, type AvailableNumber, type AvailableNumbersResponse, type CTAButtonMessage, type ConnectAgentInput, type Conversation, type ConversationContact, type ConversationLastMessage, ConversationsResource, type CreateAgentInput, type CreateBYOAAgentInput, type CreateConversationInput, type CreateConversationMessageInput, type CreateWhatsAppLinkSessionInput, type CreateWhatsAppTemplateInput, type FetchLike, type FileInfo, type ISODateTime, type ImageInfo, type ImageMessage, type ListConversationsParams, type ListSelectionMessage, type Message, type MessageReceivedEvent, type MessageReceivedMessage, type MessageRole, type MessageStatus, type MessageType, MessagesResource, type Page, type PageParams, type PaginatedResponse, type PhoneNumber, type PhoneNumberBusinessProfile, type PhoneNumberRoutingMode, type PhoneNumberString, PhoneNumbersResource, type PromptAgentInput, type PublicUser, type PublishWhatsAppTemplateInput, type QuickReplyMessage, type RequestOptions, SDK_VERSION, type SendMessageCtaImageInput, type SendMessageCtaInput, type SendMessageInput, type SendMessageTemplateInput, type SendMessageTextInput, type SendUnifiedMessageButtonInput, type SendUnifiedMessageInput, type SendUnifiedMessageMediaInput, type SubscribeConversationInput, type SubscribePhoneNumberInput, type SubscriptionActivatedEvent, type SubscriptionRevokedEvent, type TemplateMessage, type TestPingEvent, type TextMessage, type UUID, type UnifiedMessage, type UnifiedMessageButton, type UnifiedMessageButtonType, type UnifiedMessageMedia, type UnpublishWhatsAppTemplateInput, type UnsubscribePhoneNumberInput, type UpdateAgentInput, type UpdateWhatsAppTemplateInput, Wassist, WassistAPIError, WassistAuthenticationError, type WassistClientConfig, WassistConflictError, WassistConnectionError, WassistError, type WassistErrorOptions, type WassistEvent, type WassistEventBase, WassistInvalidRequestError, WassistNotFoundError, WassistPermissionError, WassistRateLimitError, WassistSignatureVerificationError, WassistTimeoutError, Webhooks, type WhatsAppAccount, type WhatsAppAccountPhoneNumber, WhatsAppAccountsResource, type WhatsAppLinkSession, type WhatsAppLinkSessionStatus, WhatsAppLinkSessionsResource, type WhatsAppTemplate, type WhatsAppTemplateAccountLink, type WhatsAppTemplateButton, type WhatsAppTemplateButtonType, type WhatsAppTemplateCategory, type WhatsAppTemplateComponent, type WhatsAppTemplateComponentExample, type WhatsAppTemplateNamedParam, type WhatsAppTemplateParameterFormat, type WhatsAppTemplatePublishResult, type WhatsAppTemplateQuality, type WhatsAppTemplateStatus, type WhatsAppTemplateUnpublishResult, type WhatsAppTemplateWithPublishResults, WhatsAppTemplatesResource };
+export { type AddNumberInput, type Agent, type AgentCreditSettings, type AgentCreditSettingsInput, type AgentDocument, type AgentHandoffTool, type AgentHandoffToolInput, type AgentImageGenerateTool, type AgentImageGenerateToolInput, type AgentMcpConfig, type AgentMcpConfigInput, type AgentMemoryKey, type AgentMemoryKeyInput, type AgentOutboundTrigger, type AgentOutboundTriggerInput, type AgentPaywallConfig, type AgentPaywallConfigInput, type AgentTool, type AgentToolInput, type AgentWakeUpConfig, type AgentWakeUpConfigInput, type AgentWebsiteTool, type AgentWebsiteToolInput, type AgentWhatsAppPhoneNumber, AgentsResource, AutoPaginatedList, type AvailableNumber, type AvailableNumbersResponse, type CTAButtonMessage, type ConnectAgentInput, type Conversation, type ConversationContact, type ConversationLastMessage, ConversationsResource, type CreateAgentInput, type CreateBYOAAgentInput, type CreateConversationInput, type CreateConversationMessageInput, type CreateWhatsAppLinkSessionInput, type CreateWhatsAppTemplateInput, type FetchLike, type FileInfo, type ISODateTime, type ImageInfo, type ImageMessage, type ListConversationsParams, type ListSelectionMessage, type Message, type MessageReceivedEvent, type MessageReceivedMessage, type MessageRole, type MessageStatus, type MessageType, MessagesResource, type Page, type PageParams, type PaginatedResponse, type PhoneNumber, type PhoneNumberBusinessProfile, type PhoneNumberRoutingMode, type PhoneNumberString, PhoneNumbersResource, type PromptAgentInput, type PublicUser, type PublishWhatsAppTemplateInput, type QuickReplyMessage, type RequestOptions, SDK_VERSION, type SendMessageCtaImageInput, type SendMessageCtaInput, type SendMessageInput, type SendMessageTemplateInput, type SendMessageTextInput, type SendUnifiedMessageButtonInput, type SendUnifiedMessageInput, type SendUnifiedMessageMediaInput, type SubscribeConversationInput, type SubscribePhoneNumberInput, type SubscriptionActivatedEvent, type SubscriptionRevokedEvent, type TemplateMessage, type TestPingEvent, type TextMessage, type UUID, type UnifiedMessage, type UnifiedMessageButton, type UnifiedMessageButtonType, type UnifiedMessageMedia, type UnpublishWhatsAppTemplateInput, type UnrecognizedWassistEvent, type UnsubscribePhoneNumberInput, type UpdateAgentInput, type UpdateWhatsAppTemplateInput, Wassist, WassistAPIError, WassistAuthenticationError, type WassistClientConfig, WassistConflictError, WassistConnectionError, WassistError, type WassistErrorOptions, type WassistEvent, type WassistEventBase, WassistInvalidRequestError, WassistNotFoundError, WassistPermissionError, WassistRateLimitError, WassistSignatureVerificationError, WassistTimeoutError, Webhooks, type WhatsAppAccount, type WhatsAppAccountPhoneNumber, WhatsAppAccountsResource, type WhatsAppLinkSession, type WhatsAppLinkSessionStatus, WhatsAppLinkSessionsResource, type WhatsAppTemplate, type WhatsAppTemplateAccountLink, type WhatsAppTemplateButton, type WhatsAppTemplateButtonType, type WhatsAppTemplateCategory, type WhatsAppTemplateComponent, type WhatsAppTemplateComponentExample, type WhatsAppTemplateNamedParam, type WhatsAppTemplateParameterFormat, type WhatsAppTemplatePublishResult, type WhatsAppTemplateQuality, type WhatsAppTemplateStatus, type WhatsAppTemplateUnpublishResult, type WhatsAppTemplateWithPublishResults, WhatsAppTemplatesResource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wassist/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Wassist SDK – the TypeScript client for the Wassist API",
   "type": "module",
   "main": "./dist/index.cjs",