@stackable-labs/sdk-extension-contracts 1.64.0 → 1.66.0

package/dist/index.d.ts

@@ -325,9 +325,28 @@ declare const ALLOWED_ICONS: readonly ["arrow-left", "calendar", "check-circle-2
 type AllowedIconName = (typeof ALLOWED_ICONS)[number];
 
 /**
- * Identity Contract
- * Types for the identity/auth event system.
+ * 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 {
+    type: 'postback';
+    actionName: string;
+    conversationId: string;
+    timestamp: string;
+}
+/** 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;
+
+/**
+ * Identity & Event Contract
+ * Types for the identity/auth event system and cross-domain event declarations.
+ */
+
 type IdentityEventType = 'identity.login' | 'identity.logout' | 'identity.refresh' | 'identity.expired';
 interface UserIdentity {
     id: string;
@@ -347,6 +366,12 @@ interface IdentityEvent {
     state: IdentityState;
     timestamp: string;
 }
+/**
+ * Union of all event types that can appear in the manifest events array.
+ * Grows as new event domains are added.
+ * Includes domain wildcards (e.g. 'identity' matches all identity.* events).
+ */
+type EventType = IdentityEventType | 'identity' | MessagingEventType | 'messaging';
 /** Base claims sent to extend:identity handlers before JWT signing */
 interface IdentityBaseClaims {
     external_id: string;
@@ -354,6 +379,8 @@ interface IdentityBaseClaims {
     name?: string;
     [key: string]: unknown;
 }
+/** Handler type for useExtendIdentity — use with useCallback for memoized handlers */
+type ExtendIdentityHandler = (claims: IdentityBaseClaims) => Record<string, unknown> | Promise<Record<string, unknown>>;
 
 /**
  * Capabilities Contract
@@ -469,7 +496,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", "events:identity", "extend:identity"];
+declare const PERMISSIONS: readonly ["context:read", "data:query", "data:fetch", "actions:toast", "actions:invoke", "events:identity", "events:messaging", "extend:identity"];
 type Permission = (typeof PERMISSIONS)[number];
 /**
  * Maps capability types to the permission required to use them.
@@ -496,7 +523,7 @@ interface ExtensionManifest {
     /** Permissions required by this extension */
     permissions: Permission[];
     /** Specific events this extension listens for (e.g. ["identity.login", "postback:add_to_cart"]) */
-    events?: string[];
+    events?: EventType[];
     /**
      * Hostnames this extension is permitted to reach via data.fetch.
      * Example: ["api.myservice.com", "cdn.myservice.com"]
@@ -838,4 +865,4 @@ interface Order {
     display_status?: OrderStatus;
 }
 
-export { ALLOWED_ICONS, type ActionInvokePayload, type Address, type AllowedIconName, type ApiError, type ApiRequest, type ApiResponse, CAPABILITY_PERMISSION_MAP, type CapabilityCall, type CapabilityRequest, type CapabilityResponse, type CapabilityType, type ContextData, type Customer, type DataField, type DataFieldType, type EncryptedPayload, type ExtendIdentityRequest, type ExtendIdentityResponse, type ExtensionManifest, type ExtensionRegistryEntry, type FetchRequest, type FetchRequestInit, type FetchResponse, type HostToSandboxMessage, type IdentityBaseClaims, type IdentityEvent, type IdentityEventType, type IdentityState, type InstanceConfig, type InstanceOption, type InvokeAction, type MarketplaceExtension, type MessengerCommand, type NamedEntity, type Order, type OrderAction, type OrderItem, type OrderStatus, type OrderStatuses, PERMISSIONS, type Permission, type Price, type SandboxToHostMessage, type Shipment, type SurfaceContext, type SurfaceLifecycleMessage, type Target, 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_DEFINITIONS, type UserIdentity, type WidgetAction, tagToComponentName };
+export { ALLOWED_ICONS, type ActionInvokePayload, type Address, type AllowedIconName, type ApiError, type ApiRequest, type ApiResponse, CAPABILITY_PERMISSION_MAP, type CapabilityCall, type CapabilityRequest, type CapabilityResponse, type CapabilityType, type ContextData, type Customer, type DataField, type DataFieldType, type EncryptedPayload, type EventType, type ExtendIdentityHandler, type ExtendIdentityRequest, type ExtendIdentityResponse, type ExtensionManifest, type ExtensionRegistryEntry, type FetchRequest, type FetchRequestInit, type FetchResponse, type HostToSandboxMessage, type IdentityBaseClaims, type IdentityEvent, type IdentityEventType, type IdentityState, type InstanceConfig, type InstanceOption, type InvokeAction, type MarketplaceExtension, type MessagingEvent, type MessagingEventHandler, type MessagingEventType, type MessagingPostbackEvent, type MessengerCommand, type NamedEntity, type Order, type OrderAction, type OrderItem, type OrderStatus, type OrderStatuses, PERMISSIONS, type Permission, type Price, type SandboxToHostMessage, type Shipment, type SurfaceContext, type SurfaceLifecycleMessage, type Target, 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_DEFINITIONS, type UserIdentity, type WidgetAction, tagToComponentName };

package/dist/index.js

@@ -308,6 +308,7 @@ var PERMISSIONS = [
   "actions:toast",
   "actions:invoke",
   "events:identity",
+  "events:messaging",
   "extend:identity"
 ];
 var CAPABILITY_PERMISSION_MAP = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackable-labs/sdk-extension-contracts",
-  "version": "1.64.0",
+  "version": "1.66.0",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",