@stackable-labs/sdk-extension-contracts 1.63.0 → 1.65.0

package/dist/index.d.ts

@@ -324,6 +324,60 @@ declare const tagToComponentName: (tag: UITag) => string;
 declare const ALLOWED_ICONS: readonly ["arrow-left", "calendar", "check-circle-2", "chevron-left", "chevron-right", "clock", "credit-card", "external-link", "help-circle", "info", "loader-2", "mail", "map-pin", "message-circle", "message-square", "package", "phone", "search", "shopping-bag", "sparkles", "truck", "user", "x-circle", "alert-circle", "book-open"];
 type AllowedIconName = (typeof ALLOWED_ICONS)[number];
 
+/**
+ * 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;
+
+/**
+ * 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;
+    email?: string;
+    name?: string;
+    avatarUrl?: string;
+    provider: string;
+    metadata?: Record<string, unknown>;
+}
+interface IdentityState {
+    authenticated: boolean;
+    user: UserIdentity | null;
+    expiresAt?: string;
+}
+interface IdentityEvent {
+    type: IdentityEventType;
+    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;
+    email?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+
 /**
  * Capabilities Contract
  * Defines the host-mediated APIs that extensions can call via RPC.
@@ -391,6 +445,8 @@ interface ContextData {
 }
 /** Union of all capability call types */
 type CapabilityCall = {
+    type: 'context.read';
+} | {
     type: 'data.query';
     payload: ApiRequest;
 } | {
@@ -403,41 +459,13 @@ type CapabilityCall = {
     type: 'actions.invoke';
     payload: ActionInvokePayload;
 } | {
-    type: 'context.read';
-} | {
-    type: 'identity.read';
-} | {
-    type: 'identity.extend';
+    type: 'extend.identity';
     payload: {
-        claims: Record<string, unknown>;
+        claims: IdentityBaseClaims;
     };
 };
 type CapabilityType = CapabilityCall['type'];
 
-/**
- * Identity Contract
- * Types for the identity/auth event system.
- */
-type AuthEventType = 'identity.login' | 'identity.logout' | 'identity.refresh' | 'identity.expired';
-interface UserIdentity {
-    id: string;
-    email?: string;
-    name?: string;
-    avatarUrl?: string;
-    provider: string;
-    metadata?: Record<string, unknown>;
-}
-interface AuthState {
-    authenticated: boolean;
-    user: UserIdentity | null;
-    expiresAt?: string;
-}
-interface AuthEvent {
-    type: AuthEventType;
-    state: AuthState;
-    timestamp: string;
-}
-
 /**
  * Instance Contract
  * Shared types for extension instances used by both host and admin.
@@ -464,7 +492,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:read", "identity:subscribe", "identity:extend"];
+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.
@@ -490,6 +518,8 @@ interface ExtensionManifest {
     targets: string[];
     /** Permissions required by this extension */
     permissions: Permission[];
+    /** Specific events this extension listens for (e.g. ["identity.login", "postback:add_to_cart"]) */
+    events?: EventType[];
     /**
      * Hostnames this extension is permitted to reach via data.fetch.
      * Example: ["api.myservice.com", "cdn.myservice.com"]
@@ -559,14 +589,14 @@ interface EncryptedPayload {
     data: number[];
 }
 /** Host asks extension to enrich identity claims before signing */
-interface IdentityExtendRequest {
-    type: 'identity-extend-request';
+interface ExtendIdentityRequest {
+    type: 'extend-identity-request';
     id: string;
-    claims: Record<string, unknown>;
+    claims: IdentityBaseClaims;
 }
 /** Extension responds with additional claims to merge into the JWT */
-interface IdentityExtendResponse {
-    type: 'identity-extend-response';
+interface ExtendIdentityResponse {
+    type: 'extend-identity-response';
     id: string;
     additionalClaims: Record<string, unknown>;
 }
@@ -585,7 +615,7 @@ type HostToSandboxMessage = {
     type: 'extension-event';
     eventType: string;
     payload: EncryptedPayload | unknown;
-} | IdentityExtendRequest;
+} | ExtendIdentityRequest;
 type SandboxToHostMessage = CapabilityRequest | {
     type: 'surface-ready';
     extensionId: string;
@@ -593,7 +623,7 @@ type SandboxToHostMessage = CapabilityRequest | {
 } | {
     type: 'extension-ready';
     extensionId: string;
-} | IdentityExtendResponse;
+} | ExtendIdentityResponse;
 
 /**
  * Ecommerce Type Definitions
@@ -831,4 +861,4 @@ interface Order {
     display_status?: OrderStatus;
 }
 
-export { ALLOWED_ICONS, type ActionInvokePayload, type Address, type AllowedIconName, type ApiError, type ApiRequest, type ApiResponse, type AuthEvent, type AuthEventType, type AuthState, CAPABILITY_PERMISSION_MAP, type CapabilityCall, type CapabilityRequest, type CapabilityResponse, type CapabilityType, type ContextData, type Customer, type DataField, type DataFieldType, type EncryptedPayload, type ExtensionManifest, type ExtensionRegistryEntry, type FetchRequest, type FetchRequestInit, type FetchResponse, type HostToSandboxMessage, type IdentityExtendRequest, type IdentityExtendResponse, 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 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 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

@@ -307,9 +307,9 @@ var PERMISSIONS = [
   "data:fetch",
   "actions:toast",
   "actions:invoke",
-  "identity:read",
-  "identity:subscribe",
-  "identity:extend"
+  "events:identity",
+  "events:messaging",
+  "extend:identity"
 ];
 var CAPABILITY_PERMISSION_MAP = {
   "context.read": "context:read",
@@ -317,8 +317,7 @@ var CAPABILITY_PERMISSION_MAP = {
   "data.fetch": "data:fetch",
   "actions.toast": "actions:toast",
   "actions.invoke": "actions:invoke",
-  "identity.read": "identity:read",
-  "identity.extend": "identity:extend"
+  "extend.identity": "extend:identity"
 };
 
 // ../../../lib/contracts/src/permissions.ts

package/package.json

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