@stackable-labs/sdk-extension-contracts 1.17.0 → 1.17.1

package/dist/index.d.ts

@@ -1,12 +1,471 @@
-export * from './common';
-export * from './api';
-export * from './app';
-export * from './components';
-export * from './capabilities';
-export * from './instance';
-export * from './permissions';
-export * from './manifest';
-export * from './marketplace';
-export * from './surface';
-export * from './rpc';
-export * from './ecommerce';
+import { MarketplaceMetadata } from '@stackable-labs/lib-contracts';
+export { AppRegistryEntry, EXTENSION_CATEGORIES, EXTENSION_VISIBILITIES, ExtensionCategory, ExtensionVisibility, MarketplaceMetadata } 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;
+    name: string;
+}
+
+interface ApiRequest {
+    action: string;
+    [key: string]: unknown;
+}
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data: T;
+    action: string;
+}
+interface ApiError {
+    error: string;
+    status?: number;
+    message?: string;
+}
+
+/**
+ * UI Component Contract
+ * Defines the fixed set of UI tags that extensions can render.
+ * The host maps these to real React components.
+ */
+declare const UI_TAGS: readonly ["ui-card", "ui-card-content", "ui-card-header", "ui-button", "ui-text", "ui-heading", "ui-badge", "ui-input", "ui-stack", "ui-inline", "ui-separator", "ui-tabs", "ui-tabs-list", "ui-tabs-trigger", "ui-tabs-content", "ui-scroll-area", "ui-avatar", "ui-avatar-image", "ui-avatar-fallback", "ui-icon", "ui-link", "ui-menu", "ui-menu-item"];
+type UITag = (typeof UI_TAGS)[number];
+/**
+ * Allowed attributes per UI tag.
+ * Host should reject any attributes not in this allowlist.
+ */
+declare const UI_TAG_ATTRIBUTES: Record<UITag, readonly string[]>;
+/**
+ * Supported icon names (subset of lucide-react).
+ * Extensions reference icons by name; host renders the actual icon component.
+ */
+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];
+
+/**
+ * Capabilities Contract
+ * Defines the host-mediated APIs that extensions can call via RPC.
+ */
+
+/** Optional init for data.fetch — mirrors RequestInit subset */
+interface FetchRequestInit {
+    /** HTTP method (default: 'GET') */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Optional request headers */
+    headers?: Record<string, string>;
+    /** Optional request body (JSON-serializable) */
+    body?: unknown;
+}
+/** Internal wire payload sent over RPC (url merged back in from positional args) */
+interface FetchRequest extends FetchRequestInit {
+    /** Full URL to fetch — must be on the extension's allowedDomains */
+    url: string;
+}
+/** Response returned to the extension */
+interface FetchResponse {
+    status: number;
+    ok: boolean;
+    data: unknown;
+}
+/** Payload for actions.toast capability */
+interface ToastPayload {
+    message: string;
+    type?: 'success' | 'error' | 'info' | 'warning';
+    duration?: number;
+}
+/** Payload for actions.invoke capability */
+interface ActionInvokePayload {
+    action: string;
+    payload?: Record<string, unknown>;
+}
+/** Context returned by context.read capability */
+interface ContextData {
+    customerId?: string;
+    customerEmail?: string;
+    [key: string]: unknown;
+}
+/** Union of all capability call types */
+type CapabilityCall = {
+    type: 'data.query';
+    payload: ApiRequest;
+} | {
+    type: 'data.fetch';
+    payload: FetchRequest;
+} | {
+    type: 'actions.toast';
+    payload: ToastPayload;
+} | {
+    type: 'actions.invoke';
+    payload: ActionInvokePayload;
+} | {
+    type: 'context.read';
+};
+type CapabilityType = CapabilityCall['type'];
+
+/**
+ * Instance Contract
+ * Shared types for extension instances used by both host and admin.
+ */
+type Theme = 'light' | 'dark';
+type InstanceSettings = {
+    theme?: Theme;
+} & Record<string, unknown>;
+interface InstanceOption {
+    id: string;
+    name: string;
+    settings?: InstanceSettings;
+}
+
+/**
+ * Permissions Contract
+ * 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"];
+type Permission = (typeof PERMISSIONS)[number];
+/**
+ * Maps capability types to the permission required to use them.
+ */
+declare const CAPABILITY_PERMISSION_MAP: Record<string, Permission>;
+
+/**
+ * Extension Manifest Schema
+ * Declared by extension developers in manifest.json.
+ */
+
+/**
+ * An extension point target identifier (e.g. "slot.header").
+ * Apps define which targets they expose; this is not a fixed list.
+ */
+type Target = string;
+interface ExtensionManifest {
+    /** Human-readable extension name */
+    name: string;
+    /** Semver version string */
+    version: string;
+    /** Extension point targets this extension renders into */
+    targets: string[];
+    /** Permissions required by this extension */
+    permissions: Permission[];
+    /**
+     * Hostnames this extension is permitted to reach via data.fetch.
+     * Example: ["api.myservice.com", "cdn.myservice.com"]
+     * Must be exact hostname strings — no wildcards, no paths.
+     * Use an empty array for extensions that do not use data.fetch.
+     */
+    allowedDomains: string[];
+}
+/**
+ * Registry entry for an installed extension (returned by /api/extensions).
+ */
+interface ExtensionRegistryEntry {
+    /** Unique extension ID */
+    id: string;
+    /** Extension manifest */
+    manifest: ExtensionManifest;
+    /** URL to the extension's JS bundle */
+    bundleUrl: string;
+    /** Whether the extension is enabled */
+    enabled: boolean;
+    /** URL to the extension icon */
+    iconUrl?: string;
+}
+
+/** Full extension with marketplace fields — stays here because it extends ExtensionRegistryEntry */
+interface MarketplaceExtension extends ExtensionRegistryEntry, MarketplaceMetadata {
+}
+
+/**
+ * Surface Lifecycle Contract
+ * Messages exchanged between host and sandbox for surface management.
+ */
+interface SurfaceContext {
+    [key: string]: unknown;
+}
+type SurfaceLifecycleMessage = {
+    type: 'createSurface';
+    surfaceId: string;
+    target: string;
+    context: SurfaceContext;
+} | {
+    type: 'updateSurfaceContext';
+    surfaceId: string;
+    context: SurfaceContext;
+} | {
+    type: 'destroySurface';
+    surfaceId: string;
+};
+
+/** Request from extension sandbox to host */
+interface CapabilityRequest {
+    type: 'capability-request';
+    id: string;
+    extensionId: string;
+    capability: CapabilityType;
+    payload: unknown;
+}
+/** Response from host to extension sandbox */
+interface CapabilityResponse {
+    type: 'capability-response';
+    id: string;
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+/** All message types that can be sent between host and sandbox */
+type HostToSandboxMessage = {
+    type: 'surface-lifecycle';
+    data: SurfaceLifecycleMessage;
+} | CapabilityResponse | {
+    type: 'context-update';
+    surfaceId: string;
+    context: Record<string, unknown>;
+};
+type SandboxToHostMessage = CapabilityRequest | {
+    type: 'surface-ready';
+    extensionId: string;
+    surfaceId: string;
+} | {
+    type: 'extension-ready';
+    extensionId: string;
+};
+
+/**
+ * Ecommerce Type Definitions
+ * Ported from zendesk-embedded-widget/app/src/types/ecommerce.ts
+ */
+interface Price {
+    currency: string;
+    amount: number;
+    precise: number;
+    rounded: string;
+    formatted: string;
+}
+interface Address {
+    id: string;
+    type: 'address';
+    first_name: string;
+    last_name: string;
+    phone: string;
+    line_1: string;
+    line_2: string;
+    city: string;
+    region: string;
+    postcode: string;
+    country: string;
+    meta?: {
+        entity_id: string;
+    };
+}
+type DataFieldType = 'data_boolean' | 'data_text' | 'data_pill' | 'data_badge' | 'data_price' | 'data_highlight' | 'data_datestamp';
+interface DataField {
+    identifier: string;
+    type: DataFieldType;
+    value: unknown;
+    editable?: boolean;
+    label?: string;
+}
+interface Customer {
+    id: string;
+    url: string;
+    type: 'guest' | 'registered';
+    name: string;
+    status?: string;
+    first_name: string;
+    last_name: string;
+    email: string;
+    phone: string;
+    data: Array<{
+        data: DataField[];
+        provider: string;
+    }>;
+    meta: {
+        tags: {
+            data: string[];
+        };
+        entity_id: string;
+        total_orders: string;
+    };
+    relationships: {
+        notes: Array<{
+            id: string;
+            type: 'note';
+            messages: string[];
+            editable: boolean;
+        }>;
+        metadata: Array<{
+            identifier: string;
+            data: DataField[];
+        }>;
+        addresses: Address[];
+    };
+}
+interface OrderStatus {
+    vendor: string;
+    color: string;
+    abbreviation: string;
+    label: string;
+}
+interface OrderStatuses {
+    note: string;
+    alerts: unknown[];
+    isPaid: boolean;
+    isShipped: boolean;
+    isRefunded: boolean;
+    isCancelled: boolean;
+    isRefundable: boolean;
+    hasBalanceOwed: boolean;
+    isCancellable: boolean;
+    isModifiable: boolean;
+    order: OrderStatus;
+    payment: OrderStatus;
+    shipping: OrderStatus;
+    refund: OrderStatus;
+}
+interface OrderItem {
+    id: string;
+    type: 'order_item' | 'custom_item';
+    sku: string;
+    name: string;
+    quantity: number;
+    refunded: number;
+    modified?: number;
+    url?: string;
+    statuses?: {
+        isShipped: boolean;
+        isModifiable: boolean;
+    };
+    meta: {
+        entity_id?: string;
+        timestamps: {
+            created_at: string;
+            updated_at: string;
+        };
+        actions?: Array<{
+            id: string;
+            type: string;
+            label: {
+                key: string;
+            };
+            url?: string;
+        }>;
+        product?: unknown;
+        price_mode?: string;
+        display_price: {
+            with_tax: {
+                unit: Price;
+                value: Price;
+            };
+            without_tax: {
+                unit: Price;
+                value: Price;
+            };
+            tax: {
+                unit: Price;
+                value: Price;
+            };
+        };
+        discount_price?: {
+            with_tax: {
+                unit: Price;
+                value: Price;
+            };
+            without_tax: {
+                unit: Price;
+                value: Price;
+            };
+            tax: {
+                unit: Price;
+                value: Price;
+            };
+        };
+        vendor?: string;
+    };
+    relationships?: {
+        shipping?: {
+            parcels?: Array<{
+                id: string;
+                shipment_status: string;
+                trackings: Array<{
+                    tracking_number: string;
+                    carrier: string;
+                    carrier_code: string;
+                    service_code?: string;
+                    url?: string;
+                }>;
+                name?: string;
+                timestamps?: {
+                    created_at: string;
+                };
+            }>;
+        };
+    };
+}
+interface Shipment {
+    id: string;
+    shipping_address: Address;
+}
+interface OrderAction {
+    id: string;
+    type: 'order_action';
+    label: {
+        key: string;
+    };
+    url?: string;
+    confirm?: boolean;
+}
+interface Order {
+    id: string;
+    type: 'order';
+    url: string;
+    transaction_id: string;
+    statuses: OrderStatuses;
+    actions?: OrderAction[];
+    billing_address?: Address;
+    shipments: Shipment[];
+    relationships: {
+        items: {
+            data: OrderItem[];
+        };
+        transactions?: {
+            data: unknown[];
+        };
+        customer: {
+            data: {
+                type: 'customer';
+                id: string;
+                url: string;
+                name: string;
+                phone: string;
+                email: string;
+            };
+        };
+    };
+    meta: {
+        timestamps: {
+            created_at: string;
+            updated_at: string;
+        };
+        tax_mode: string;
+        entity_id: string;
+        tags: {
+            data: string[];
+        };
+        display_price: {
+            with_tax: Price;
+            without_tax: Price;
+            tax: Price;
+        };
+        display_balance_price?: {
+            with_tax: Price;
+        };
+        refundable_balance_price?: {
+            with_tax: Price;
+        };
+    };
+    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 ExtensionManifest, type ExtensionRegistryEntry, type FetchRequest, type FetchRequestInit, type FetchResponse, type HostToSandboxMessage, type InstanceOption, type InstanceSettings, type MarketplaceExtension, 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, UI_TAGS, UI_TAG_ATTRIBUTES };

package/dist/index.js

@@ -1,13 +1,133 @@
-export * from './common';
-export * from './api';
-export * from './app';
-export * from './components';
-export * from './capabilities';
-export * from './instance';
-export * from './permissions';
-export * from './manifest';
-export * from './marketplace';
-export * from './surface';
-export * from './rpc';
-export * from './ecommerce';
-//# sourceMappingURL=index.js.map
+// src/components.ts
+var UI_TAGS = [
+  "ui-card",
+  "ui-card-content",
+  "ui-card-header",
+  "ui-button",
+  "ui-text",
+  "ui-heading",
+  "ui-badge",
+  "ui-input",
+  "ui-stack",
+  "ui-inline",
+  "ui-separator",
+  "ui-tabs",
+  "ui-tabs-list",
+  "ui-tabs-trigger",
+  "ui-tabs-content",
+  "ui-scroll-area",
+  "ui-avatar",
+  "ui-avatar-image",
+  "ui-avatar-fallback",
+  "ui-icon",
+  "ui-link",
+  "ui-menu",
+  "ui-menu-item"
+];
+var UI_TAG_ATTRIBUTES = {
+  "ui-card": ["className", "onClick"],
+  "ui-card-content": ["className"],
+  "ui-card-header": ["className"],
+  "ui-button": ["variant", "size", "disabled", "onClick", "type", "className", "title"],
+  "ui-text": ["className", "tone"],
+  "ui-heading": ["level", "className"],
+  "ui-badge": ["variant", "tone", "className"],
+  "ui-input": ["type", "placeholder", "value", "onChange", "disabled", "className", "id"],
+  "ui-stack": ["gap", "direction", "align", "className"],
+  "ui-inline": ["gap", "align", "className"],
+  "ui-separator": ["className"],
+  "ui-tabs": ["defaultValue", "className"],
+  "ui-tabs-list": ["className"],
+  "ui-tabs-trigger": ["value", "className"],
+  "ui-tabs-content": ["value", "className"],
+  "ui-scroll-area": ["className"],
+  "ui-avatar": ["className"],
+  "ui-avatar-image": ["src", "alt", "className"],
+  "ui-avatar-fallback": ["className"],
+  "ui-icon": ["name", "size", "className"],
+  "ui-link": ["href", "target", "rel", "className"],
+  "ui-menu-item": ["icon", "label", "description", "onClick", "className"],
+  "ui-menu": ["title", "className"]
+};
+var ALLOWED_ICONS = [
+  "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"
+];
+
+// src/permissions.ts
+var PERMISSIONS = [
+  "context:read",
+  "data:query",
+  "data:fetch",
+  "actions:toast",
+  "actions:invoke"
+];
+var CAPABILITY_PERMISSION_MAP = {
+  "context.read": "context:read",
+  "data.query": "data:query",
+  "data.fetch": "data:fetch",
+  "actions.toast": "actions:toast",
+  "actions.invoke": "actions:invoke"
+};
+
+// ../../../lib/contracts/src/permissions.ts
+var SUPER_ROLE = {
+  ADMIN: "org:super_admin"
+};
+var ORG_ROLE = {
+  ADMIN: "org:admin",
+  OWNER: "org:owner",
+  MEMBER: "org:member"
+};
+var EDITOR_ROLES = [
+  SUPER_ROLE.ADMIN,
+  ORG_ROLE.ADMIN,
+  ORG_ROLE.OWNER
+];
+var VIEWER_ROLES = [
+  ...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,
+  UI_TAGS,
+  UI_TAG_ATTRIBUTES
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackable-labs/sdk-extension-contracts",
-  "version": "1.17.0",
+  "version": "1.17.1",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -11,9 +11,6 @@
       "default": "./dist/index.js"
     }
   },
-  "dependencies": {
-    "@stackable-labs/lib-contracts": "workspace:*"
-  },
   "description": "TypeScript contracts and interfaces for Stackable extensions.",
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {

package/dist/api.d.ts

@@ -1,14 +0,0 @@
-export interface ApiRequest {
-    action: string;
-    [key: string]: unknown;
-}
-export interface ApiResponse<T = unknown> {
-    success: boolean;
-    data: T;
-    action: string;
-}
-export interface ApiError {
-    error: string;
-    status?: number;
-    message?: string;
-}

package/dist/api.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":""}

package/dist/app.d.ts

@@ -1 +0,0 @@
-export type { AppRegistryEntry } from '@stackable-labs/lib-contracts';

package/dist/app.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":""}