@topolo/sdk 0.11.11 → 0.13.0

package/dist/index.d.ts

@@ -254,6 +254,10 @@ interface TopoloActionCatalogEntry {
 }
 interface TopoloActionAgentContract {
     docsUrl?: string;
+    resourceContext?: {
+        kind?: string;
+        required?: boolean;
+    };
     resource?: {
         kind?: string;
         idPath?: string;
@@ -513,6 +517,7 @@ declare function compactActionCatalogEntry(action: TopoloActionCatalogEntry): {
     requiredPermission: string;
     requiredInput: string[];
     resourceType: string | null;
+    resultResourceType: string | null;
     exampleInput: Record<string, unknown> | null;
     exampleInputAvailable: boolean;
     docsUrl: string | null;
@@ -1248,47 +1253,167 @@ declare class TopoloOAuth {
     }): Promise<TokenResponse>;
 }
 
+declare function validateTopoloWidgetResponse(response: unknown): TopoloWidgetValidationResult;
+
 declare const TOPOLO_WIDGET_ENDPOINT = "/api/widget";
 declare const TOPOLO_WIDGET_REFRESH_INTERVAL_MS = 60000;
-type TopoloWidgetType = "stats" | "recent-activity" | "quick-actions" | "notifications" | "chart";
+declare const TOPOLO_WIDGET_CONTRACT_VERSION: "2.0.0";
+type TopoloWidgetType = "stats" | "chart" | "activity" | "notifications" | "actions";
+type TopoloWidgetContext = "personal" | "organization" | "workspace" | "resource";
+type TopoloWidgetSize = "compact" | "medium" | "wide" | "full";
+type TopoloWidgetStatus = "ready" | "empty" | "unavailable" | "stale" | "error";
+interface TopoloWidgetPresentation {
+    title: string;
+    description?: string;
+    contexts: TopoloWidgetContext[];
+    supportedSizes: TopoloWidgetSize[];
+    defaultSize: TopoloWidgetSize;
+}
+interface TopoloWidgetResourceBinding {
+    resourceType: string;
+    resourceId?: string;
+    requiredPermissions: string[];
+}
+interface TopoloWidgetState {
+    status: TopoloWidgetStatus;
+    observedAt: string;
+    lastSuccessfulAt?: string;
+    code?: string;
+    message?: string;
+}
+interface TopoloWidgetRefreshPolicy {
+    intervalSeconds: number;
+    timeoutSeconds: number;
+    maxAgeSeconds: number;
+    staleWhileRevalidateSeconds: number;
+}
+interface TopoloWidgetConfigurationOption {
+    value: string;
+    label: string;
+}
+interface TopoloWidgetConfigurationField {
+    key: string;
+    label: string;
+    type: "string" | "number" | "boolean" | "select" | "multi-select" | "date-range";
+    required: boolean;
+    options?: TopoloWidgetConfigurationOption[];
+}
+interface TopoloWidgetConfiguration {
+    allowMultipleInstances: boolean;
+    fields: TopoloWidgetConfigurationField[];
+    defaults: Record<string, unknown>;
+}
+interface TopoloWidgetDrilldown {
+    id: string;
+    label: string;
+    href: string;
+}
+interface TopoloWidgetActionRecovery {
+    mode: "not_applicable" | "retry" | "compensating_action";
+    actionId?: string;
+    instructions: string;
+}
+interface TopoloWidgetActionBinding {
+    id: string;
+    label: string;
+    actionId: string;
+    resourceType: string;
+    resourceId?: string;
+    input: Record<string, unknown>;
+    requiresConfirmation: boolean;
+    destructive: boolean;
+    effects: string[];
+    verification: string[];
+    recovery: TopoloWidgetActionRecovery;
+}
+interface TopoloWidgetLocalization {
+    locale: string;
+    titleKey: string;
+    descriptionKey?: string;
+    /**
+     * English source text for `titleKey`. Hosts already fall back to their own
+     * title when the key misses, so this changes no rendering — it exists so the
+     * key HAS a source string: the i18n extractor reads a sibling literal named
+     * after the key's field, and without one the key never reaches a catalog and
+     * cannot be translated into any locale.
+     */
+    title?: string;
+    /** English source text for `descriptionKey`. See `title`. */
+    description?: string;
+}
+interface TopoloWidgetAccessibility {
+    label: string;
+    description?: string;
+}
 interface TopoloWidgetBase {
+    id: string;
+    version: string;
     appId: string;
     serviceName: string;
     serviceIcon?: string;
     type: TopoloWidgetType;
     lastUpdated: string;
-    snapshot: TopoloWidgetSnapshotMetadata;
+    presentation: TopoloWidgetPresentation;
+    resource: TopoloWidgetResourceBinding;
+    state: TopoloWidgetState;
+    refresh: TopoloWidgetRefreshPolicy;
+    configuration: TopoloWidgetConfiguration;
+    drilldowns: TopoloWidgetDrilldown[];
+    controls: TopoloWidgetActionBinding[];
+    localization: TopoloWidgetLocalization;
+    accessibility: TopoloWidgetAccessibility;
+}
+type TopoloWidgetMetricSemantic = "gauge" | "counter" | "rate" | "duration" | "currency" | "percentage";
+type TopoloWidgetMetricAggregation = "last" | "sum" | "average" | "minimum" | "maximum" | "count" | "distinct_count";
+interface TopoloWidgetPeriod {
+    start: string;
+    end: string;
+    timezone: string;
+}
+interface TopoloWidgetDimension {
+    key: string;
+    label: string;
+    value: string;
 }
-interface TopoloWidgetMetric {
-    key?: string;
+interface TopoloWidgetMetricComparison {
+    value: number;
+    absoluteChange: number;
+    percentageChange?: number;
+    direction: "up" | "down" | "flat";
     label: string;
-    value: string | number;
-    change?: number;
-    changeLabel?: string;
-    icon?: string;
+    period: TopoloWidgetPeriod;
+}
+interface TopoloWidgetSeriesPoint {
+    timestamp: string;
+    value: number;
+    dimensions: TopoloWidgetDimension[];
 }
-interface TopoloWidgetSnapshotMetric {
+interface TopoloWidgetSeries {
+    id: string;
+    label: string;
+    unit: string;
+    points: TopoloWidgetSeriesPoint[];
+}
+interface TopoloWidgetMetric {
     key: string;
     label: string;
     value: number;
-    unit?: string;
-    change?: number;
-    changeLabel?: string;
-}
-interface TopoloWidgetSnapshotMetadata {
-    presetKey?: string;
-    audience?: string;
-    scope?: string;
-    scopeLabel?: string;
-    generatedAt?: string;
-    summary: string;
-    defaultMetricKeys?: string[];
-    availableMetrics?: TopoloWidgetSnapshotMetric[];
-    highlights?: string[];
+    unit: string;
+    semantic: TopoloWidgetMetricSemantic;
+    aggregation: TopoloWidgetMetricAggregation;
+    period: TopoloWidgetPeriod;
+    dimensions: TopoloWidgetDimension[];
+    comparison?: TopoloWidgetMetricComparison;
+    series?: TopoloWidgetSeries;
 }
 interface TopoloStatsWidget extends TopoloWidgetBase {
     type: "stats";
-    stats: TopoloWidgetMetric[];
+    metrics: TopoloWidgetMetric[];
+}
+interface TopoloChartWidget extends TopoloWidgetBase {
+    type: "chart";
+    chartType: "line" | "bar" | "area" | "pie" | "donut";
+    series: TopoloWidgetSeries[];
 }
 interface TopoloWidgetActivityItem {
     id: string;
@@ -1296,60 +1421,74 @@ interface TopoloWidgetActivityItem {
     description?: string;
     timestamp: string;
     icon?: string;
-    link?: string;
+    drilldownId?: string;
+    actionId?: string;
 }
-interface TopoloRecentActivityWidget extends TopoloWidgetBase {
-    type: "recent-activity";
+interface TopoloActivityWidget extends TopoloWidgetBase {
+    type: "activity";
     activities: TopoloWidgetActivityItem[];
 }
-interface TopoloWidgetActionItem {
-    id: string;
-    label: string;
-    icon?: string;
-    link: string;
-    primary?: boolean;
-}
-interface TopoloQuickActionsWidget extends TopoloWidgetBase {
-    type: "quick-actions";
-    actions: TopoloWidgetActionItem[];
-}
 interface TopoloWidgetNotificationItem {
     id: string;
     title: string;
     message: string;
-    type: "info" | "warning" | "error" | "success";
+    severity: "info" | "warning" | "error" | "success";
     timestamp: string;
     read: boolean;
-    link?: string;
+    drilldownId?: string;
+    actionId?: string;
 }
 interface TopoloNotificationsWidget extends TopoloWidgetBase {
     type: "notifications";
     notifications: TopoloWidgetNotificationItem[];
     unreadCount: number;
 }
-interface TopoloChartWidget extends TopoloWidgetBase {
-    type: "chart";
-    chartType: "line" | "bar" | "pie" | "donut";
-    title: string;
-    data: {
-        labels: string[];
-        values: number[];
-    };
+interface TopoloActionsWidget extends TopoloWidgetBase {
+    type: "actions";
+    actions: TopoloWidgetActionBinding[];
 }
-type TopoloWidget = TopoloStatsWidget | TopoloRecentActivityWidget | TopoloQuickActionsWidget | TopoloNotificationsWidget | TopoloChartWidget;
-type TopoloWidgetWithOptionalMetadata<T extends TopoloWidget> = Omit<T, "appId" | "serviceName" | "lastUpdated"> & Partial<Pick<TopoloWidgetBase, "appId" | "serviceName" | "lastUpdated">>;
-type TopoloWidgetDraft = TopoloWidget extends infer Widget ? Widget extends TopoloWidget ? TopoloWidgetWithOptionalMetadata<Widget> : never : never;
-interface TopoloWidgetApiResponse {
-    success: boolean;
+type TopoloWidget = TopoloStatsWidget | TopoloChartWidget | TopoloActivityWidget | TopoloNotificationsWidget | TopoloActionsWidget;
+type TopoloWidgetWithOptionalServiceMetadata<T extends TopoloWidget> = Omit<T, "appId" | "serviceName" | "lastUpdated"> & Partial<Pick<TopoloWidgetBase, "appId" | "serviceName" | "lastUpdated">>;
+type TopoloWidgetDraft = TopoloWidget extends infer Widget ? Widget extends TopoloWidget ? TopoloWidgetWithOptionalServiceMetadata<Widget> : never : never;
+interface TopoloWidgetApiSuccessResponse {
+    success: true;
+    contractVersion: typeof TOPOLO_WIDGET_CONTRACT_VERSION;
+    appId: string;
+    serviceName: string;
+    generatedAt: string;
     widgets: TopoloWidget[];
-    error?: string;
 }
+interface TopoloWidgetApiError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    retryAfter?: string;
+}
+interface TopoloWidgetApiErrorResponse {
+    success: false;
+    contractVersion: typeof TOPOLO_WIDGET_CONTRACT_VERSION;
+    appId: string;
+    serviceName: string;
+    generatedAt: string;
+    widgets: [];
+    error: TopoloWidgetApiError;
+}
+type TopoloWidgetApiResponse = TopoloWidgetApiSuccessResponse | TopoloWidgetApiErrorResponse;
 interface TopoloWidgetResponseOptions {
     appId: string;
     serviceName: string;
     widgets: TopoloWidgetDraft[];
     now?: Date | string;
 }
+interface TopoloWidgetErrorResponseOptions {
+    appId: string;
+    serviceName: string;
+    code: string;
+    message: string;
+    retryable: boolean;
+    retryAfter?: Date | string;
+    now?: Date | string;
+}
 interface TopoloWidgetValidationResult {
     ok: boolean;
     errors: string[];
@@ -1363,13 +1502,12 @@ interface TopoloWidgetConfig {
     refreshInterval: number;
 }
 declare function defineTopoloStatsWidget(widget: Omit<TopoloStatsWidget, "type">): TopoloStatsWidget;
-declare function defineTopoloRecentActivityWidget(widget: Omit<TopoloRecentActivityWidget, "type">): TopoloRecentActivityWidget;
-declare function defineTopoloQuickActionsWidget(widget: Omit<TopoloQuickActionsWidget, "type">): TopoloQuickActionsWidget;
-declare function defineTopoloNotificationsWidget(widget: Omit<TopoloNotificationsWidget, "type">): TopoloNotificationsWidget;
 declare function defineTopoloChartWidget(widget: Omit<TopoloChartWidget, "type">): TopoloChartWidget;
-declare function createTopoloWidgetResponse({ appId, serviceName, widgets, now, }: TopoloWidgetResponseOptions): TopoloWidgetApiResponse;
-declare function createTopoloWidgetError(error: string): TopoloWidgetApiResponse;
-declare function validateTopoloWidgetResponse(response: unknown): TopoloWidgetValidationResult;
+declare function defineTopoloActivityWidget(widget: Omit<TopoloActivityWidget, "type">): TopoloActivityWidget;
+declare function defineTopoloNotificationsWidget(widget: Omit<TopoloNotificationsWidget, "type">): TopoloNotificationsWidget;
+declare function defineTopoloActionsWidget(widget: Omit<TopoloActionsWidget, "type">): TopoloActionsWidget;
+declare function createTopoloWidgetResponse({ appId, serviceName, widgets, now, }: TopoloWidgetResponseOptions): TopoloWidgetApiSuccessResponse;
+declare function createTopoloWidgetError({ appId, serviceName, code, message, retryable, retryAfter, now, }: TopoloWidgetErrorResponseOptions): TopoloWidgetApiErrorResponse;
 
 /**
  * Convenience factory that returns a ready-to-use typed Topolo client plus
@@ -1386,4 +1524,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { ACTION_CATALOG_DIGEST_ALGORITHM, type ActionContractManifest, type ActionContractSource, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetActionItem, type TopoloWidgetActivityItem, type TopoloWidgetApiResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetDraft, type TopoloWidgetMetric, type TopoloWidgetNotificationItem, type TopoloWidgetResponseOptions, type TopoloWidgetSnapshotMetadata, type TopoloWidgetSnapshotMetric, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, listApplicationDirectory, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };
+export { ACTION_CATALOG_DIGEST_ALGORITHM, type ActionContractManifest, type ActionContractSource, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetDimension, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, listApplicationDirectory, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };