@stackable-labs/sdk-extension-contracts 2.23.0 → 2.25.0

package/dist/index.d.ts

@@ -436,14 +436,36 @@ interface IdentityEvent {
         timestamp: ISOTimestamp;
     };
 }
-/** Base claims sent to extend:identity handlers before JWT signing */
+/** Base claims sent to identity.extend handlers before JWT signing */
 interface IdentityBaseClaims {
     external_id: string;
     email?: string;
     name?: string;
     [key: string]: unknown;
 }
-/** Handler type for useExtendIdentity — use with useCallback for memoized handlers */
+/** Standard JWT claims (host/Lambda always allow these; declaration is redundant). */
+declare const STANDARD_IDENTITY_CLAIM_KEYS: ReadonlySet<string>;
+/** RFC 7519 registered + Zendesk-managed claims — host-side sanitizer always
+ *  wins on collision, so these must never appear in manifest.identityClaims. */
+declare const RESERVED_IDENTITY_CLAIM_KEYS: ReadonlySet<string>;
+/** Valid identityClaims key format: lowercase identifier, ≤64 chars. */
+declare const IDENTITY_CLAIM_KEY_PATTERN: RegExp;
+/** Maximum number of custom identityClaims entries per extension. */
+declare const IDENTITY_CLAIMS_MAX_KEYS = 20;
+/** Maximum length of any single string value sent through identity.extend / custom_claims. */
+declare const IDENTITY_CLAIM_MAX_STRING_VALUE_LEN = 256;
+/**
+ * Handler type for useExtendIdentity. Use with useCallback for memoized handlers.
+ *
+ * Returned keys are filtered host-side against the extension's
+ * `manifest.identityClaims` declaration:
+ * - Standard JWT overrides (`external_id`, `email`, `name`) always allowed
+ * - Custom keys must be declared in `manifest.identityClaims`
+ * - Undeclared keys are dropped with a console.warn
+ *
+ * Values must be `string | number | boolean` for inclusion in the signed JWT;
+ * non-primitive values are dropped by the Lambda sanitizer.
+ */
 type ExtendIdentityHandler = (claims: IdentityBaseClaims) => Record<string, unknown> | Promise<Record<string, unknown>>;
 
 /**
@@ -549,6 +571,23 @@ interface ContextData {
 /** Keys managed exclusively by the host RPC layer — must not appear in surface-level context */
 declare const RESERVED_CONTEXT_KEYS: readonly ["identity", "messaging", "settings"];
 type ReservedContextKey = typeof RESERVED_CONTEXT_KEYS[number];
+/**
+ * Payload sent from extension → host for `identity.extend`.
+ *
+ * `patch` is a partial set of claims the extension wants to merge into its
+ * cached enrichment slot on the host. Host filters the patch against
+ * `manifest.identityClaims` (same rules as the initial-login enrichment path),
+ * re-signs the JWT, updates `identityState.user.metadata`, and broadcasts
+ * `identity:refresh`.
+ */
+interface IdentityExtendPayload {
+    patch: Record<string, unknown>;
+}
+/** Response returned to the extension after the host completes the re-sign flow. */
+interface IdentityExtendResponse {
+    /** The newly-signed JWT — same token that was pushed to outbound auth (Zendesk). */
+    token: string;
+}
 /** Union of all capability call types */
 type CapabilityCall = {
     type: 'context.read';
@@ -565,10 +604,8 @@ type CapabilityCall = {
     type: 'actions.invoke';
     payload: ActionInvokePayload;
 } | {
-    type: 'extend.identity';
-    payload: {
-        claims: IdentityBaseClaims;
-    };
+    type: 'identity.extend';
+    payload: IdentityExtendPayload;
 };
 type CapabilityType = CapabilityCall['type'];
 
@@ -694,7 +731,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", "events:activity", "extend:identity"];
+declare const PERMISSIONS: readonly ["context:read", "data:query", "data:fetch", "actions:toast", "actions:invoke", "identity:extend", "events:identity", "events:messaging", "events:activity"];
 type Permission = (typeof PERMISSIONS)[number];
 /**
  * Maps capability types (dot notation, used in code) to the permission
@@ -706,7 +743,7 @@ declare const CAPABILITY_PERMISSION_MAP: {
     readonly 'data.fetch': "data:fetch";
     readonly 'actions.toast': "actions:toast";
     readonly 'actions.invoke': "actions:invoke";
-    readonly 'extend.identity': "extend:identity";
+    readonly 'identity.extend': "identity:extend";
 };
 /** Capability key type — dot-notation API names (e.g., 'data.query', 'actions.toast') */
 type Capability = keyof typeof CAPABILITY_PERMISSION_MAP;
@@ -751,6 +788,24 @@ interface ExtensionManifest {
     permissions: Permission[];
     /** Specific events this extension listens for (e.g. ["identity:login", "messaging:postback:Buy Now"]) */
     events?: EventType[];
+    /**
+     * Specific custom identity claim keys this extension contributes via
+     * `useExtendIdentity`. Required (non-empty) when `permissions` includes
+     * `identity:extend` and the handler returns custom keys.
+     *
+     * Standard JWT claims (`external_id`, `email`, `name`) are exempt — they're
+     * always allowed as overrides without explicit declaration.
+     *
+     * Constraints (enforced at runtime by the host; install-time bundle scan
+     * adds the upload-side gate):
+     * - Keys must match /^[a-z_][a-z0-9_]{0,63}$/ (snake_case, ≤64 chars)
+     * - Reserved JWT/Zendesk claim names rejected
+     * - Max 20 declared keys per extension
+     *
+     * Returned-but-undeclared keys are dropped at runtime with a console.warn.
+     * Example: ["loyalty_tier", "verified", "preferred_pronoun"]
+     */
+    identityClaims?: string[];
     /**
      * Hostnames this extension is permitted to reach via data.fetch.
      * Prefer exact hostnames. Use `*.<suffix>` wildcards only if you need any
@@ -1111,4 +1166,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_EVENT, INVOKE_ACTION, 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 NewConversationPayload, type Order, type OrderAction, type OrderItem, type OrderStatus, type OrderStatuses, PERMISSIONS, type Permission, type Price, RESERVED_CONTEXT_KEYS, type ReservedContextKey, 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 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 };

package/dist/index.js

@@ -405,6 +405,27 @@ var IDENTITY_EVENT = {
   REFRESH: "refresh",
   EXPIRED: "expired"
 };
+var STANDARD_IDENTITY_CLAIM_KEYS = /* @__PURE__ */ new Set(["external_id", "email", "name"]);
+var RESERVED_IDENTITY_CLAIM_KEYS = /* @__PURE__ */ new Set([
+  // RFC 7519 registered claims
+  "iss",
+  "sub",
+  "aud",
+  "exp",
+  "nbf",
+  "iat",
+  "jti",
+  // Zendesk Messaging standard claims (Lambda sets these unconditionally)
+  "scope",
+  "external_id",
+  "email",
+  "email_verified",
+  "name",
+  "user_fields"
+]);
+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/activity.ts
 var ACTIVITY_EVENT = {
@@ -424,10 +445,10 @@ var PERMISSIONS = [
   "data:fetch",
   "actions:toast",
   "actions:invoke",
+  "identity:extend",
   "events:identity",
   "events:messaging",
-  "events:activity",
-  "extend:identity"
+  "events:activity"
 ];
 var CAPABILITY_PERMISSION_MAP = {
   "context.read": "context:read",
@@ -435,7 +456,7 @@ var CAPABILITY_PERMISSION_MAP = {
   "data.fetch": "data:fetch",
   "actions.toast": "actions:toast",
   "actions.invoke": "actions:invoke",
-  "extend.identity": "extend:identity"
+  "identity.extend": "identity:extend"
 };
 var EVENT_HOOK_PERMISSION_MAP = {
   useIdentityEvent: "events:identity",
@@ -454,4 +475,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_EVENT, INVOKE_ACTION, PERMISSIONS, RESERVED_CONTEXT_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, 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 };

package/package.json

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