@stackable-labs/sdk-extension-contracts 1.69.2 → 1.71.0

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-import { MarketplaceMetadata } from '@stackable-labs/lib-contracts';
-export { AppRegistryEntry, EXTENSION_CATEGORIES, EXTENSION_VISIBILITIES, ExtensionCategory, ExtensionVisibility, MarketplaceMetadata } from '@stackable-labs/lib-contracts';
+import { ISOTimestamp, MarketplaceMetadata } from '@stackable-labs/lib-contracts';
+export { AppRegistryEntry, ClerkOrgId, ClerkUserId, EXTENSION_CATEGORIES, EXTENSION_VISIBILITIES, ExtensionCategory, ExtensionVisibility, ISOTimestamp, MarketplaceMetadata, asClerkOrgId, asClerkUserId, asISOTimestamp } from '@stackable-labs/lib-contracts';
 
 /**
  * Shared primitive types used across contracts.
  */
+
 /** Lightweight reference to a named entity (e.g. extension, instance). */
 interface NamedEntity {
     id: string;
@@ -324,30 +325,13 @@ 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;
-/** 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.
+ * Types for the identity/auth event system.
  */
 
-type IdentityEventType = 'identity.login' | 'identity.logout' | 'identity.refresh' | 'identity.expired';
+/** Domain-stripped identity event names. Hooks accept these directly (e.g., useIdentityEvent('login', ...)). */
+type IdentityEventType = 'login' | 'logout' | 'refresh' | 'expired';
 interface UserIdentity {
     id: string;
     email?: string;
@@ -359,19 +343,15 @@ interface UserIdentity {
 interface IdentityState {
     authenticated: boolean;
     user: UserIdentity | null;
-    expiresAt?: string;
+    expiresAt?: ISOTimestamp;
 }
 interface IdentityEvent {
-    type: IdentityEventType;
-    state: IdentityState;
-    timestamp: string;
+    eventName: IdentityEventType;
+    data: {
+        state: IdentityState;
+        timestamp: ISOTimestamp;
+    };
 }
-/**
- * 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;
@@ -481,6 +461,68 @@ type CapabilityCall = {
 };
 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).
+ */
+/** Well-known activity event names (aligned with GA conventions). Hosts can emit any custom string. */
+type WellKnownActivityEvent = 'page_view' | 'click' | 'product_view' | 'add_to_cart' | 'purchase' | 'search' | 'form_submit';
+/** Domain-stripped activity event names. Hooks accept these directly (e.g., useActivityEvent('product_view', ...)). */
+type ActivityEventType = WellKnownActivityEvent | string;
+/** Normalized activity event payload */
+interface ActivityEvent {
+    eventName: ActivityEventType;
+    data: Record<string, unknown>;
+}
+/** Handler type for useActivityEvent — use with useCallback for memoized handlers */
+type ActivityEventHandler = (event: ActivityEvent) => void;
+
+/**
+ * Unified Event Type
+ * Shared union across all event domains. Used in manifest `events` array and the generic `useEvent` hook.
+ * Domain-specific hooks accept the un-prefixed types (e.g., 'login' not 'identity:login').
+ */
+
+/** Known event domains. Used by window.stackable.emit() and broadcast routing. */
+type EventDomain = 'activity' | 'identity' | 'messaging';
+/** Domain-specific event type mapping. Maps each domain to its event name union. */
+type EventTypeMap = {
+    activity: ActivityEventType;
+    identity: IdentityEventType;
+    messaging: MessagingEventType;
+};
+/** Fully-qualified event type: domain wildcard or domain:eventName. Used in manifest `events` array and `useEvent` hook. */
+type EventType = EventDomain | {
+    [D in EventDomain]: `${D}:${EventTypeMap[D]}`;
+}[EventDomain];
+
 /**
  * Instance Contract
  * Shared types for extension instances used by both host and admin.
@@ -507,7 +549,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", "events:messaging", "extend:identity"];
+declare const PERMISSIONS: readonly ["context:read", "data:query", "data:fetch", "actions:toast", "actions:invoke", "events:identity", "events:messaging", "events:activity", "extend:identity"];
 type Permission = (typeof PERMISSIONS)[number];
 /**
  * Maps capability types to the permission required to use them.
@@ -533,7 +575,7 @@ 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"]) */
+    /** Specific events this extension listens for (e.g. ["identity:login", "messaging:postback:add_to_cart"]) */
     events?: EventType[];
     /**
      * Hostnames this extension is permitted to reach via data.fetch.
@@ -652,6 +694,7 @@ type SandboxToHostMessage = CapabilityRequest | {
  * Ecommerce Type Definitions
  * Ported from zendesk-embedded-widget/app/src/types/ecommerce.ts
  */
+
 interface Price {
     currency: string;
     amount: number;
@@ -756,8 +799,8 @@ interface OrderItem {
     meta: {
         entity_id?: string;
         timestamps: {
-            created_at: string;
-            updated_at: string;
+            created_at: ISOTimestamp;
+            updated_at: ISOTimestamp;
         };
         actions?: Array<{
             id: string;
@@ -813,7 +856,7 @@ interface OrderItem {
                 }>;
                 name?: string;
                 timestamps?: {
-                    created_at: string;
+                    created_at: ISOTimestamp;
                 };
             }>;
         };
@@ -861,8 +904,8 @@ interface Order {
     };
     meta: {
         timestamps: {
-            created_at: string;
-            updated_at: string;
+            created_at: ISOTimestamp;
+            updated_at: ISOTimestamp;
         };
         tax_mode: string;
         entity_id: string;
@@ -884,4 +927,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 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 MessagingContext, 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, RESERVED_CONTEXT_KEYS, type ReservedContextKey, 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 ActivityEvent, type ActivityEventHandler, type ActivityEventType, 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 EventDomain, 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 MessagingContext, 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, RESERVED_CONTEXT_KEYS, type ReservedContextKey, 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 WellKnownActivityEvent, type WidgetAction, tagToComponentName };

package/dist/index.js

@@ -1,3 +1,36 @@
+// ../../../lib/contracts/src/base.ts
+var asISOTimestamp = (value) => value;
+var asClerkUserId = (value) => value;
+var asClerkOrgId = (value) => value;
+
+// ../../../lib/contracts/src/permissions.ts
+var SUPER_ROLE = {
+  ADMIN: "org:super_admin"
+};
+var ORG_ROLE = {
+  ADMIN: "org:admin",
+  OWNER: "org:owner"};
+var EDITOR_ROLES = [
+  SUPER_ROLE.ADMIN,
+  ORG_ROLE.ADMIN,
+  ORG_ROLE.OWNER
+];
+[
+  ...Object.values(SUPER_ROLE),
+  ...Object.values(EDITOR_ROLES)
+];
+
+// ../../../lib/contracts/src/marketplace.ts
+var EXTENSION_CATEGORIES = [
+  "commerce",
+  "support",
+  "analytics",
+  "productivity",
+  "communication",
+  "other"
+];
+var EXTENSION_VISIBILITIES = ["public", "protected"];
+
 // src/components.ts
 var UI_TAG_DEFINITIONS = {
   "ui-card": {
@@ -312,6 +345,7 @@ var PERMISSIONS = [
   "actions:invoke",
   "events:identity",
   "events:messaging",
+  "events:activity",
   "extend:identity"
 ];
 var CAPABILITY_PERMISSION_MAP = {
@@ -323,32 +357,4 @@ var CAPABILITY_PERMISSION_MAP = {
   "extend.identity": "extend:identity"
 };
 
-// ../../../lib/contracts/src/permissions.ts
-var SUPER_ROLE = {
-  ADMIN: "org:super_admin"
-};
-var ORG_ROLE = {
-  ADMIN: "org:admin",
-  OWNER: "org:owner"};
-var EDITOR_ROLES = [
-  SUPER_ROLE.ADMIN,
-  ORG_ROLE.ADMIN,
-  ORG_ROLE.OWNER
-];
-[
-  ...Object.values(SUPER_ROLE),
-  ...Object.values(EDITOR_ROLES)
-];
-
-// ../../../lib/contracts/src/marketplace.ts
-var EXTENSION_CATEGORIES = [
-  "commerce",
-  "support",
-  "analytics",
-  "productivity",
-  "communication",
-  "other"
-];
-var EXTENSION_VISIBILITIES = ["public", "protected"];
-
-export { ALLOWED_ICONS, CAPABILITY_PERMISSION_MAP, EXTENSION_CATEGORIES, EXTENSION_VISIBILITIES, PERMISSIONS, RESERVED_CONTEXT_KEYS, UI_TAGS, UI_TAG_ATTRIBUTES, UI_TAG_ATTRIBUTE_VALUES, UI_TAG_CATEGORIES, UI_TAG_CHILDREN, UI_TAG_DEFINITIONS, tagToComponentName };
+export { ALLOWED_ICONS, CAPABILITY_PERMISSION_MAP, EXTENSION_CATEGORIES, EXTENSION_VISIBILITIES, PERMISSIONS, RESERVED_CONTEXT_KEYS, UI_TAGS, UI_TAG_ATTRIBUTES, UI_TAG_ATTRIBUTE_VALUES, UI_TAG_CATEGORIES, UI_TAG_CHILDREN, UI_TAG_DEFINITIONS, asClerkOrgId, asClerkUserId, asISOTimestamp, tagToComponentName };

package/package.json

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