@stackable-labs/sdk-extension-contracts 2.30.0 → 3.0.0

package/dist/index.d.ts

@@ -468,6 +468,396 @@ declare const IDENTITY_CLAIM_MAX_STRING_VALUE_LEN = 256;
  */
 type ExtendIdentityHandler = (claims: IdentityBaseClaims) => Record<string, unknown> | Promise<Record<string, unknown>>;
 
+/**
+ * Messaging Contract — all messaging-domain types (events + send capability).
+ */
+
+/** Messaging context — conversation and app identifiers. */
+interface MessagingContext {
+    conversationId?: string | null;
+    appId?: string | null;
+}
+/** Messaging event subscription types — 'postback' for all, 'postback:<actionName>' for specific */
+type MessagingEventType = 'postback' | `postback:${string}`;
+/** Normalized postback event payload */
+interface MessagingPostbackEvent {
+    eventName: 'postback';
+    data: {
+        /**
+         * The postback button's display text (Zendesk-specific).
+         * NOTE: This is NOT an event system field — `eventType` and `eventName` are our event system
+         * conventions. `actionName` is a domain-specific payload field identifying which button was
+         * clicked, and lives inside `data` alongside other Zendesk messaging fields.
+         */
+        actionName: string;
+        conversationId: string;
+        timestamp: ISOTimestamp;
+    };
+}
+/** Union of all messaging events (extensible for future event types) */
+type MessagingEvent = MessagingPostbackEvent;
+/** Handler type for useMessagingEvent — use with useCallback for memoized handlers */
+type MessagingEventHandler = (event: MessagingEvent) => void;
+/**
+ * Primitives allowed as values in metadata (both message-level and action-level).
+ * Sunco rejects nested objects/arrays at the wire layer; total metadata capped at 4KB.
+ */
+type ActionMetadataValue = string | number | boolean | null;
+/**
+ * Format of a message body. Drives which Sunco wire field the host populates:
+ *   - 'text'      → Sunco `content.text`         (plain — default; max 4096 chars)
+ *   - 'markdown'  → Sunco `content.markdownText` (server-converts to htmlText)
+ *   - 'html'      → Sunco `content.htmlText`     (max 4096 chars; mutex with markdownText)
+ *
+ * Sunco auto-converts markdown/html to plain text for channels that don't support
+ * rich text — graceful cross-channel fallback.
+ */
+type TextFormat = 'text' | 'markdown' | 'html';
+/** Common base — fields available on EVERY message kind. */
+interface BaseMessagePayload {
+    /**
+     * When true, disables the user's chat input while this is the most recent
+     * message in the conversation. Useful for guided / forced-button-response flows.
+     * Maps to Sunco `content.blockChatInput`.
+     */
+    disableUserInput?: boolean;
+    /**
+     * Caller-supplied metadata. Merged with host-injected `stackable.*` block
+     * (extensionId / capabilityCallId / instanceId — non-overridable by extensions).
+     * Values are primitives; total ≤4KB. Doesn't render in the Messenger widget.
+     */
+    metadata?: Record<string, ActionMetadataValue>;
+}
+/**
+ * Mixin for message kinds that support a text body + format. Extended by
+ * text (required override), and future image/file/carousel (optional caption).
+ */
+interface TextEnabledPayload {
+    body?: string;
+    bodyFormat?: TextFormat;
+}
+/** Common base for all action types — shared label + per-action metadata. */
+interface BaseAction {
+    label: string;
+    /** Optional flat metadata attached to this action. Primitives only; 4KB cap total. */
+    metadata?: Record<string, ActionMetadataValue>;
+}
+/**
+ * Reply action — clicking inserts a visible user-reply bubble carrying `payload`
+ * back to the conversation, as if the user typed it.
+ *
+ * MUTUALLY EXCLUSIVE — a `reply` action cannot appear in the same `actions[]`
+ * array as any other action type. Sunco returns 400 if mixed. The host validates
+ * pre-flight and surfaces `invalid_message` to the extension.
+ */
+interface ReplyAction extends BaseAction {
+    type: 'reply';
+    /** Opaque string. Sunco rejects non-string payloads. For structured data, use `metadata`. */
+    payload: string;
+    /** Optional icon URL rendered next to the reply pill. */
+    iconUrl?: string;
+}
+/**
+ * Link action — clicking opens `url` in a new tab/window. No bubble inserted.
+ * Freely mixable with other non-reply action types.
+ */
+interface LinkAction extends BaseAction {
+    type: 'link';
+    url: string;
+}
+/**
+ * Postback action — clicking fires a server-side `conversation:postback` webhook
+ * to the Stackable backend with the full `payload` + any `metadata`. NO visible
+ * bubble inserted. Extensions receive postback events via declared event handlers
+ * (see `events:messaging` permission). Freely mixable with other non-reply types.
+ */
+interface PostbackAction extends BaseAction {
+    type: 'postback';
+    /** Opaque string. Sunco rejects non-string payloads. For structured data, use `metadata`. */
+    payload: string;
+}
+/**
+ * Location-request action — prompts the user to share their device location.
+ * Response arrives as a separate `location`-type message inbound to the conversation.
+ * Freely mixable with other non-reply action types.
+ */
+interface LocationRequestAction extends BaseAction {
+    type: 'locationRequest';
+}
+/**
+ * Union of message-level action types. Used as the type of `actions` on
+ * top-level message payloads. For carousel and list ITEMS (future), see
+ * `MessageItemAction` (a subset that excludes `reply` and `locationRequest`).
+ */
+type MessageAction = ReplyAction | LinkAction | PostbackAction | LocationRequestAction;
+/**
+ * Subset of action types valid inside future carousel/list items. Sunco's
+ * `actionSubset` schema excludes `reply` and `locationRequest`. Surfaced as a
+ * separate type so the SDK compile-time prevents using them where Sunco doesn't.
+ */
+type MessageItemAction = LinkAction | PostbackAction;
+/**
+ * Text message — plain text body with optional in-message actions.
+ *
+ * Inherits from:
+ *   - BaseMessagePayload  → disableUserInput, metadata
+ *   - TextEnabledPayload  → body (narrowed to REQUIRED here), bodyFormat
+ */
+interface SendTextMessagePayload extends BaseMessagePayload, TextEnabledPayload {
+    kind: 'text';
+    /**
+     * Body text — THE message itself for the `text` kind. Required.
+     * Narrows the optional `body` from TextEnabledPayload to required for this kind.
+     * Sunco caps at 4096 chars (across all of text/htmlText/markdownText).
+     */
+    body: string;
+    /**
+     * Optional in-message actions. Reply actions are mutex with all other types
+     * (host validates and surfaces `invalid_message`). Practical max ~10 per message.
+     */
+    actions?: MessageAction[];
+    /**
+     * Echoed payload from a prior `reply` action click. Set by the host on inbound
+     * messages; not generally set by extension authors on outbound. Maps to Sunco
+     * `textMessage.payload`.
+     */
+    payload?: string;
+}
+/**
+ * Image message — embedded image with optional caption + action buttons.
+ * Use for product photos, screenshots, visual help / troubleshooting.
+ *
+ * Inherits from:
+ *   - BaseMessagePayload  → disableUserInput, metadata
+ *   - TextEnabledPayload  → body (optional caption alongside the image), bodyFormat
+ *
+ * Spec note: Sunco `imageMessage.mediaUrl` has no explicit maxLength in the OpenAPI
+ * spec. `altText` is OPTIONAL — Sunco defaults it to the URL's filename if omitted.
+ */
+interface SendImageMessagePayload extends BaseMessagePayload, TextEnabledPayload {
+    kind: 'image';
+    /** Public URL or pre-signed URL. Must respond with Content-Type `image/*`. */
+    url: string;
+    /**
+     * Optional accessibility label, max 128 chars. If omitted, Sunco populates
+     * from the URL's filename.
+     */
+    altText?: string;
+    /** Optional in-message actions. Reply-mutex rule applies (see ReplyAction). */
+    actions?: MessageAction[];
+}
+/**
+ * File message — embedded file attachment (PDF, document, etc.) with optional
+ * caption. Use for return labels, receipts, NDAs, referral docs, warranty paperwork.
+ *
+ * Inherits from:
+ *   - BaseMessagePayload  → disableUserInput, metadata
+ *   - TextEnabledPayload  → body (optional caption alongside the file), bodyFormat
+ *
+ * Spec note: file messages have NO actions field (Sunco fileMessage schema doesn't
+ * support them). `altText` optional, defaults to filename. `mediaSize` + `mediaType`
+ * are readonly server-set fields.
+ */
+interface SendFileMessagePayload extends BaseMessagePayload, TextEnabledPayload {
+    kind: 'file';
+    /** Public URL or pre-signed URL. Content-Type drives how Sunco renders the attachment. */
+    url: string;
+    /**
+     * Optional accessibility label, max 128 chars. If omitted, Sunco populates
+     * from the URL's filename.
+     */
+    altText?: string;
+}
+/**
+ * Shared item shape used by carousel payloads (and reserved for future list
+ * support if/when the Zendesk Messenger Widget adds rendering — see note on
+ * SendMessagePayload below). Maps to Sunco's single `item` schema.
+ *
+ * Spec note: `actions` is REQUIRED with min 1 / max 3 entries, all from the
+ * `MessageItemAction` subset (no reply, no locationRequest). The tuple-rest
+ * type enforces ≥1 at compile time; max 3 is host-validated.
+ */
+interface MessageItem {
+    /** Required, 1-128 chars. */
+    title: string;
+    /** Optional, max 128 chars. */
+    description?: string;
+    /** Optional image URL, max 2048 chars. */
+    imageUrl?: string;
+    /** Optional accessibility label, max 128 chars. */
+    altText?: string;
+    /** Display size for the item's image. Maps to Sunco `item.size`. */
+    imageSize?: 'compact' | 'large';
+    /** REQUIRED 1-3 actions per item. Subset only — no reply, no locationRequest. */
+    actions: [MessageItemAction, ...MessageItemAction[]];
+    /** Optional flat metadata, primitives only, 4KB cap. */
+    metadata?: Record<string, ActionMetadataValue>;
+}
+/**
+ * Carousel message — horizontally scrolling cards. THE conversational-commerce
+ * primitive: product recommendations, size/color pickers, search results with
+ * images, multi-option selection.
+ *
+ * Inherits from BaseMessagePayload only — Sunco `carouselMessage` has no
+ * settable text body (its `text` field is a readonly server-set fallback for
+ * channels that don't render carousels). Use a separate text message before
+ * the carousel if you need an intro.
+ *
+ * Spec note: NO message-level `actions` field — Sunco carouselMessage doesn't
+ * define one. Actions live per-card on `items[].actions`. `items` REQUIRED,
+ * min 1, max 10.
+ */
+interface SendCarouselMessagePayload extends BaseMessagePayload {
+    kind: 'carousel';
+    /** 1-10 cards. Host validates the cap. */
+    items: MessageItem[];
+    /** Optional carousel-level display tweaks. */
+    displaySettings?: {
+        /**
+         * How carousel images render. `horizontal` (default) or `square`. Only
+         * supported by Facebook Messenger, Web Messenger, Android SDK, iOS SDK;
+         * other channels ignore.
+         */
+        imageAspectRatio?: 'horizontal' | 'square';
+    };
+}
+/**
+ * Payload for messaging.send capability — discriminated by `kind`.
+ */
+type SendMessagePayload = SendTextMessagePayload | SendImageMessagePayload | SendFileMessagePayload | SendCarouselMessagePayload;
+/** Discriminator literals — one per supported kind. */
+type MessagePayloadKind = SendMessagePayload['kind'];
+/**
+ * Canonical example payloads — one per kind. Single source of truth for the
+ * developer-docs cookbook generator. `satisfies` makes TypeScript verify every
+ * example is a valid `SendMessagePayload` AND that every kind has an entry, so
+ * adding a new kind (or renaming/removing a field) breaks the build until the
+ * example is updated alongside the type.
+ */
+declare const MESSAGING_SEND_EXAMPLES: {
+    readonly text: {
+        readonly kind: "text";
+        readonly body: "Order approved ✓";
+        readonly actions: [{
+            readonly type: "reply";
+            readonly label: "Got it";
+            readonly payload: "ACK";
+        }, {
+            readonly type: "reply";
+            readonly label: "Show details";
+            readonly payload: "DETAILS";
+        }];
+    };
+    readonly image: {
+        readonly kind: "image";
+        readonly url: "https://cdn.example.com/products/widget-blue.jpg";
+        readonly altText: "Blue widget — model A24";
+        readonly body: "Here is the product you asked about:";
+        readonly actions: [{
+            readonly type: "link";
+            readonly label: "View on site";
+            readonly url: "https://example.com/p/widget-a24";
+        }];
+    };
+    readonly file: {
+        readonly kind: "file";
+        readonly url: "https://cdn.example.com/receipts/order-12345.pdf";
+        readonly altText: "Receipt for order #12345";
+        readonly body: "Your receipt is attached.";
+    };
+    readonly carousel: {
+        readonly kind: "carousel";
+        readonly items: [{
+            readonly title: "Widget A24 — Blue";
+            readonly description: "In stock — ships in 1-2 days";
+            readonly imageUrl: "https://cdn.example.com/products/widget-blue.jpg";
+            readonly actions: [{
+                readonly type: "link";
+                readonly label: "View";
+                readonly url: "https://example.com/p/widget-a24-blue";
+            }, {
+                readonly type: "postback";
+                readonly label: "Add to cart";
+                readonly payload: "add_to_cart:widget-a24-blue";
+            }];
+        }, {
+            readonly title: "Widget A24 — Red";
+            readonly description: "Limited stock";
+            readonly imageUrl: "https://cdn.example.com/products/widget-red.jpg";
+            readonly actions: [{
+                readonly type: "link";
+                readonly label: "View";
+                readonly url: "https://example.com/p/widget-a24-red";
+            }, {
+                readonly type: "postback";
+                readonly label: "Add to cart";
+                readonly payload: "add_to_cart:widget-a24-red";
+            }];
+        }];
+        readonly displaySettings: {
+            readonly imageAspectRatio: "horizontal";
+        };
+    };
+};
+/**
+ * Canonical example actions — one per action type. Single source of truth for
+ * the developer-docs cookbook generator. The mapped-type satisfies clause
+ * forces each entry to be the SPECIFIC narrowed action (reply must have a
+ * payload; locationRequest must not; etc.) AND that every action type
+ * literal has an entry, so adding/removing/renaming an action breaks the
+ * build until the example is updated alongside the type.
+ */
+declare const MESSAGING_ACTION_EXAMPLES: {
+    readonly reply: {
+        readonly type: "reply";
+        readonly label: "Got it";
+        readonly payload: "ACK";
+    };
+    readonly link: {
+        readonly type: "link";
+        readonly label: "View on site";
+        readonly url: "https://example.com/p/widget-a24";
+    };
+    readonly postback: {
+        readonly type: "postback";
+        readonly label: "Add to cart";
+        readonly payload: "add_to_cart:widget-a24";
+    };
+    readonly locationRequest: {
+        readonly type: "locationRequest";
+        readonly label: "Share location";
+    };
+};
+/**
+ * Response from messaging.send — minimum surface for extensions to correlate
+ * with their own UI. Full Sunco response shape intentionally not surfaced.
+ */
+interface SendMessageResponse {
+    messageId: string;
+    /** ISO 8601 — when Sunco persisted the message. */
+    receivedAt: string;
+}
+/**
+ * Codes that the extension author can meaningfully react to in UI. These are
+ * the only codes that surface via the `useMessaging` hook's `state.error` and
+ * cause `send()` to throw. End-users can act on each (retry, fix payload,
+ * back off rate-limit, retry transient upstream issue). The wider
+ * `SendMessageErrorCode` includes host-handled codes that the SDK swallows.
+ */
+type SendMessageActionableErrorCode = 'invalid_message' | 'rate_limited' | 'upstream_error';
+/**
+ * Full wire taxonomy returned by the host's `messaging.send` capability.
+ * Superset of `SendMessageActionableErrorCode` plus host-handled codes that
+ * the SDK does NOT surface to extension state:
+ * - `no_conversation`: framework logs `console.info`; extension can pre-empt via `useContextData().messaging?.conversationId`
+ * - `reauth_required`: framework logs `console.warn`; server flips `messagingDisconnected:true` → admin dashboard surfaces Reconnect UI
+ * - `forbidden`: framework logs `console.warn`; extension manifest/permission misconfig — admin/dev resolves
+ *
+ * Lowercase snake_case to match the existing convention (e.g.
+ * `reauth_required` on the reconnect endpoint).
+ */
+type SendMessageErrorCode = SendMessageActionableErrorCode | 'no_conversation' | 'reauth_required' | 'forbidden';
+
 /**
  * Capabilities Contract
  * Defines the host-mediated APIs that extensions can call via RPC.
@@ -552,11 +942,6 @@ interface ActionInvokePayload {
     action: InvokeAction;
     payload?: Record<string, unknown>;
 }
-/** Messaging context — conversation and app identifiers */
-interface MessagingContext {
-    conversationId?: string | null;
-    appId?: string | null;
-}
 /** Context returned by context.read capability */
 interface ContextData {
     customerId?: string;
@@ -606,36 +991,12 @@ type CapabilityCall = {
 } | {
     type: 'identity.extend';
     payload: IdentityExtendPayload;
+} | {
+    type: 'messaging.send';
+    payload: SendMessagePayload;
 };
 type CapabilityType = CapabilityCall['type'];
 
-/**
- * Messaging Contract
- * Types for the messaging event system (postback buttons, etc.).
- */
-
-/** Messaging event subscription types — 'postback' for all, 'postback:<actionName>' for specific */
-type MessagingEventType = 'postback' | `postback:${string}`;
-/** Normalized postback event payload */
-interface MessagingPostbackEvent {
-    eventName: 'postback';
-    data: {
-        /**
-         * The postback button's display text (Zendesk-specific).
-         * NOTE: This is NOT an event system field — `eventType` and `eventName` are our event system
-         * conventions. `actionName` is a domain-specific payload field identifying which button was
-         * clicked, and lives inside `data` alongside other Zendesk messaging fields.
-         */
-        actionName: string;
-        conversationId: string;
-        timestamp: ISOTimestamp;
-    };
-}
-/** Union of all messaging events (extensible for future event types) */
-type MessagingEvent = MessagingPostbackEvent;
-/** Handler type for useMessagingEvent — use with useCallback for memoized handlers */
-type MessagingEventHandler = (event: MessagingEvent) => void;
-
 /**
  * Activity Event Contract
  * Types for the activity event system (host-to-extension push events).
@@ -690,6 +1051,7 @@ interface InstanceConfig {
         identityProvider?: string;
         messagingIntegrationId?: string;
         messagingAppId?: string;
+        messagingDisplayName?: string;
     } & Record<string, unknown>;
     secrets?: {
         identityKey?: string;
@@ -731,7 +1093,7 @@ interface InstanceOption {
  * Extensions declare required permissions in their manifest.
  * Host enforces: capability calls must be a subset of granted permissions.
  */
-declare const PERMISSIONS: readonly ["context:read", "data:query", "data:fetch", "actions:toast", "actions:invoke", "identity:extend", "events:identity", "events:messaging", "events:activity"];
+declare const PERMISSIONS: readonly ["context:read", "data:query", "data:fetch", "actions:toast", "actions:invoke", "messaging:send", "identity:extend", "events:identity", "events:messaging", "events:activity"];
 type Permission = (typeof PERMISSIONS)[number];
 /**
  * Maps capability types (dot notation, used in code) to the permission
@@ -744,20 +1106,38 @@ declare const CAPABILITY_PERMISSION_MAP: {
     readonly 'actions.toast': "actions:toast";
     readonly 'actions.invoke': "actions:invoke";
     readonly 'identity.extend': "identity:extend";
+    readonly 'messaging.send': "messaging:send";
 };
 /** Capability key type — dot-notation API names (e.g., 'data.query', 'actions.toast') */
 type Capability = keyof typeof CAPABILITY_PERMISSION_MAP;
 /**
- * Maps event hook names (as used in source code) to the permission required to
- * subscribe via that hook.
+ * Maps event-hook names to the permission required to subscribe via that hook.
+ * Use this when iterating event hooks specifically (e.g., docs that talk about
+ * the manifest `events` array, drift guardrails over `## events:*` doc sections).
+ * For broader "any hook → permission" detection, use HOOK_PERMISSION_MAP below.
  */
 declare const EVENT_HOOK_PERMISSION_MAP: {
     readonly useIdentityEvent: "events:identity";
     readonly useMessagingEvent: "events:messaging";
     readonly useActivityEvent: "events:activity";
 };
-/** Event-hook key type — hook names (e.g., 'useIdentityEvent', 'useMessagingEvent') */
+/** Event-hook key type — hook names that subscribe to host events. */
 type EventHook = keyof typeof EVENT_HOOK_PERMISSION_MAP;
+/**
+ * Maps React hook names (as used in source code) to the permission required to
+ * use that hook. Covers event hooks AND non-event hooks (useExtendIdentity,
+ * useMessaging) so static analysis can detect the full author-facing surface.
+ * Composed from EVENT_HOOK_PERMISSION_MAP + the non-event additions.
+ */
+declare const HOOK_PERMISSION_MAP: {
+    readonly useMessaging: "messaging:send";
+    readonly useExtendIdentity: "identity:extend";
+    readonly useIdentityEvent: "events:identity";
+    readonly useMessagingEvent: "events:messaging";
+    readonly useActivityEvent: "events:activity";
+};
+/** Hook key type — React hook names (e.g., 'useIdentityEvent', 'useMessaging'). */
+type Hook = keyof typeof HOOK_PERMISSION_MAP;
 
 /**
  * Extension Manifest Schema
@@ -908,6 +1288,9 @@ type HostToSandboxMessage = {
 } | {
     type: 'surface-lifecycle';
     data: SurfaceLifecycleMessage;
+} | {
+    type: 'messaging-lifecycle';
+    enabled: boolean;
 } | {
     type: 'extension-encryption-key';
     encryptionKey: string;
@@ -1166,4 +1549,4 @@ interface Order {
 declare const TEMPLATE_FLAVORS: readonly ["minimal", "starter", "kitchen-sink"];
 type TemplateFlavor = typeof TEMPLATE_FLAVORS[number];
 
-export { ACTIVITY_EVENT, ALLOWED_ICONS, type ActionInvokePayload, type ActionPayloadMap, type ActivityEvent, type ActivityEventHandler, type ActivityEventType, type Address, type AllowedIconName, type ApiError, type ApiRequest, type ApiResponse, CAPABILITY_PERMISSION_MAP, type Capability, type CapabilityCall, type CapabilityRequest, type CapabilityResponse, type CapabilityType, type ContextData, type ConversationField, type ConversationTags, type Customer, type DataField, type DataFieldType, EVENT_HOOK_PERMISSION_MAP, type EncryptedPayload, type EventDomain, type EventHook, type EventType, type ExtendIdentityHandler, type ExtendIdentityRequest, type ExtendIdentityResponse, type ExtensionGroup, type ExtensionManifest, type ExtensionRegistryEntry, type FetchRequest, type FetchRequestInit, type FetchResponse, type HostToSandboxMessage, IDENTITY_CLAIMS_MAX_KEYS, IDENTITY_CLAIM_KEY_PATTERN, IDENTITY_CLAIM_MAX_STRING_VALUE_LEN, IDENTITY_EVENT, INVOKE_ACTION, type IdentityBaseClaims, type IdentityEvent, type IdentityEventType, type IdentityExtendPayload, type IdentityExtendResponse, type IdentityState, type InstanceConfig, type InstanceOption, type InvokeAction, type MarketplaceExtension, type MessagingContext, type MessagingEvent, type MessagingEventHandler, type MessagingEventType, type MessagingPostbackEvent, type MessengerCommand, type NamedEntity, type NewConversationPayload, type Order, type OrderAction, type OrderItem, type OrderStatus, type OrderStatuses, PERMISSIONS, type Permission, type Price, RESERVED_CONTEXT_KEYS, RESERVED_IDENTITY_CLAIM_KEYS, type ReservedContextKey, STANDARD_IDENTITY_CLAIM_KEYS, SURFACE_TARGET, type SandboxToHostMessage, type Shipment, type SurfaceContext, type SurfaceLifecycleMessage, type SurfaceTarget, TEMPLATE_FLAVORS, type Target, type TemplateFlavor, type Theme, type ToastPayload, type UITag, type UITagCategory, UI_TAGS, UI_TAG_ATTRIBUTES, UI_TAG_ATTRIBUTE_VALUES, UI_TAG_CATEGORIES, UI_TAG_CHILDREN, UI_TAG_CHILD_ONLY, UI_TAG_COMPOUND, UI_TAG_DEFINITIONS, UI_TAG_SELF_CLOSING, type UserIdentity, type WellKnownActivityEvent, type WidgetAction, tagToComponentName };
+export { ACTIVITY_EVENT, ALLOWED_ICONS, type ActionInvokePayload, type ActionMetadataValue, type ActionPayloadMap, type ActivityEvent, type ActivityEventHandler, type ActivityEventType, type Address, type AllowedIconName, type ApiError, type ApiRequest, type ApiResponse, type BaseAction, type BaseMessagePayload, CAPABILITY_PERMISSION_MAP, type Capability, type CapabilityCall, type CapabilityRequest, type CapabilityResponse, type CapabilityType, type ContextData, type ConversationField, type ConversationTags, type Customer, type DataField, type DataFieldType, EVENT_HOOK_PERMISSION_MAP, type EncryptedPayload, type EventDomain, type EventHook, type EventType, type ExtendIdentityHandler, type ExtendIdentityRequest, type ExtendIdentityResponse, type ExtensionGroup, type ExtensionManifest, type ExtensionRegistryEntry, type FetchRequest, type FetchRequestInit, type FetchResponse, HOOK_PERMISSION_MAP, type Hook, type HostToSandboxMessage, IDENTITY_CLAIMS_MAX_KEYS, IDENTITY_CLAIM_KEY_PATTERN, IDENTITY_CLAIM_MAX_STRING_VALUE_LEN, IDENTITY_EVENT, INVOKE_ACTION, type IdentityBaseClaims, type IdentityEvent, type IdentityEventType, type IdentityExtendPayload, type IdentityExtendResponse, type IdentityState, type InstanceConfig, type InstanceOption, type InvokeAction, type LinkAction, type LocationRequestAction, MESSAGING_ACTION_EXAMPLES, MESSAGING_SEND_EXAMPLES, type MarketplaceExtension, type MessageAction, type MessageItem, type MessageItemAction, type MessagePayloadKind, type MessagingContext, type MessagingEvent, type MessagingEventHandler, type MessagingEventType, type MessagingPostbackEvent, type MessengerCommand, type NamedEntity, type NewConversationPayload, type Order, type OrderAction, type OrderItem, type OrderStatus, type OrderStatuses, PERMISSIONS, type Permission, type PostbackAction, type Price, RESERVED_CONTEXT_KEYS, RESERVED_IDENTITY_CLAIM_KEYS, type ReplyAction, type ReservedContextKey, STANDARD_IDENTITY_CLAIM_KEYS, SURFACE_TARGET, type SandboxToHostMessage, type SendCarouselMessagePayload, type SendFileMessagePayload, type SendImageMessagePayload, type SendMessageActionableErrorCode, type SendMessageErrorCode, type SendMessagePayload, type SendMessageResponse, type SendTextMessagePayload, type Shipment, type SurfaceContext, type SurfaceLifecycleMessage, type SurfaceTarget, TEMPLATE_FLAVORS, type Target, type TemplateFlavor, type TextEnabledPayload, type TextFormat, type Theme, type ToastPayload, type UITag, type UITagCategory, UI_TAGS, UI_TAG_ATTRIBUTES, UI_TAG_ATTRIBUTE_VALUES, UI_TAG_CATEGORIES, UI_TAG_CHILDREN, UI_TAG_CHILD_ONLY, UI_TAG_COMPOUND, UI_TAG_DEFINITIONS, UI_TAG_SELF_CLOSING, type UserIdentity, type WellKnownActivityEvent, type WidgetAction, tagToComponentName };

package/dist/index.js

@@ -427,6 +427,63 @@ var IDENTITY_CLAIM_KEY_PATTERN = /^[a-z_][a-z0-9_]{0,63}$/;
 var IDENTITY_CLAIMS_MAX_KEYS = 20;
 var IDENTITY_CLAIM_MAX_STRING_VALUE_LEN = 256;
 
+// src/messaging.ts
+var MESSAGING_SEND_EXAMPLES = {
+  text: {
+    kind: "text",
+    body: "Order approved \u2713",
+    actions: [
+      { type: "reply", label: "Got it", payload: "ACK" },
+      { type: "reply", label: "Show details", payload: "DETAILS" }
+    ]
+  },
+  image: {
+    kind: "image",
+    url: "https://cdn.example.com/products/widget-blue.jpg",
+    altText: "Blue widget \u2014 model A24",
+    body: "Here is the product you asked about:",
+    actions: [
+      { type: "link", label: "View on site", url: "https://example.com/p/widget-a24" }
+    ]
+  },
+  file: {
+    kind: "file",
+    url: "https://cdn.example.com/receipts/order-12345.pdf",
+    altText: "Receipt for order #12345",
+    body: "Your receipt is attached."
+  },
+  carousel: {
+    kind: "carousel",
+    items: [
+      {
+        title: "Widget A24 \u2014 Blue",
+        description: "In stock \u2014 ships in 1-2 days",
+        imageUrl: "https://cdn.example.com/products/widget-blue.jpg",
+        actions: [
+          { type: "link", label: "View", url: "https://example.com/p/widget-a24-blue" },
+          { type: "postback", label: "Add to cart", payload: "add_to_cart:widget-a24-blue" }
+        ]
+      },
+      {
+        title: "Widget A24 \u2014 Red",
+        description: "Limited stock",
+        imageUrl: "https://cdn.example.com/products/widget-red.jpg",
+        actions: [
+          { type: "link", label: "View", url: "https://example.com/p/widget-a24-red" },
+          { type: "postback", label: "Add to cart", payload: "add_to_cart:widget-a24-red" }
+        ]
+      }
+    ],
+    displaySettings: { imageAspectRatio: "horizontal" }
+  }
+};
+var MESSAGING_ACTION_EXAMPLES = {
+  reply: { type: "reply", label: "Got it", payload: "ACK" },
+  link: { type: "link", label: "View on site", url: "https://example.com/p/widget-a24" },
+  postback: { type: "postback", label: "Add to cart", payload: "add_to_cart:widget-a24" },
+  locationRequest: { type: "locationRequest", label: "Share location" }
+};
+
 // src/activity.ts
 var ACTIVITY_EVENT = {
   CLICK: "click",
@@ -445,6 +502,7 @@ var PERMISSIONS = [
   "data:fetch",
   "actions:toast",
   "actions:invoke",
+  "messaging:send",
   "identity:extend",
   "events:identity",
   "events:messaging",
@@ -456,13 +514,19 @@ var CAPABILITY_PERMISSION_MAP = {
   "data.fetch": "data:fetch",
   "actions.toast": "actions:toast",
   "actions.invoke": "actions:invoke",
-  "identity.extend": "identity:extend"
+  "identity.extend": "identity:extend",
+  "messaging.send": "messaging:send"
 };
 var EVENT_HOOK_PERMISSION_MAP = {
   useIdentityEvent: "events:identity",
   useMessagingEvent: "events:messaging",
   useActivityEvent: "events:activity"
 };
+var HOOK_PERMISSION_MAP = {
+  ...EVENT_HOOK_PERMISSION_MAP,
+  useMessaging: "messaging:send",
+  useExtendIdentity: "identity:extend"
+};
 
 // src/manifest.ts
 var SURFACE_TARGET = {
@@ -475,4 +539,4 @@ var SURFACE_TARGET = {
 // src/scaffold.ts
 var TEMPLATE_FLAVORS = ["minimal", "starter", "kitchen-sink"];
 
-export { ACTIVITY_EVENT, ALLOWED_ICONS, CAPABILITY_PERMISSION_MAP, EVENT_HOOK_PERMISSION_MAP, EXTENSION_CATEGORY, EXTENSION_VISIBILITY, IDENTITY_CLAIMS_MAX_KEYS, IDENTITY_CLAIM_KEY_PATTERN, IDENTITY_CLAIM_MAX_STRING_VALUE_LEN, IDENTITY_EVENT, INVOKE_ACTION, PERMISSIONS, RESERVED_CONTEXT_KEYS, RESERVED_IDENTITY_CLAIM_KEYS, STANDARD_IDENTITY_CLAIM_KEYS, SURFACE_TARGET, TEMPLATE_FLAVORS, UI_TAGS, UI_TAG_ATTRIBUTES, UI_TAG_ATTRIBUTE_VALUES, UI_TAG_CATEGORIES, UI_TAG_CHILDREN, UI_TAG_CHILD_ONLY, UI_TAG_COMPOUND, UI_TAG_DEFINITIONS, UI_TAG_SELF_CLOSING, asClerkOrgId, asClerkUserId, asISOTimestamp, tagToComponentName };
+export { ACTIVITY_EVENT, ALLOWED_ICONS, CAPABILITY_PERMISSION_MAP, EVENT_HOOK_PERMISSION_MAP, EXTENSION_CATEGORY, EXTENSION_VISIBILITY, HOOK_PERMISSION_MAP, IDENTITY_CLAIMS_MAX_KEYS, IDENTITY_CLAIM_KEY_PATTERN, IDENTITY_CLAIM_MAX_STRING_VALUE_LEN, IDENTITY_EVENT, INVOKE_ACTION, MESSAGING_ACTION_EXAMPLES, MESSAGING_SEND_EXAMPLES, PERMISSIONS, RESERVED_CONTEXT_KEYS, RESERVED_IDENTITY_CLAIM_KEYS, STANDARD_IDENTITY_CLAIM_KEYS, SURFACE_TARGET, TEMPLATE_FLAVORS, UI_TAGS, UI_TAG_ATTRIBUTES, UI_TAG_ATTRIBUTE_VALUES, UI_TAG_CATEGORIES, UI_TAG_CHILDREN, UI_TAG_CHILD_ONLY, UI_TAG_COMPOUND, UI_TAG_DEFINITIONS, UI_TAG_SELF_CLOSING, asClerkOrgId, asClerkUserId, asISOTimestamp, tagToComponentName };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackable-labs/sdk-extension-contracts",
-  "version": "2.30.0",
+  "version": "3.0.0",
   "type": "module",
   "sideEffects": false,
   "private": false,