@topolo/sdk 0.8.3 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -31,6 +31,17 @@ interface AgentIdentity {
31
31
  agentName?: string;
32
32
  }
33
33
 
34
+ interface TopoloActionValidationIssue {
35
+ path: string;
36
+ code: string;
37
+ message: string;
38
+ }
39
+ interface TopoloActionValidationResult {
40
+ valid: boolean;
41
+ errors: TopoloActionValidationIssue[];
42
+ }
43
+ declare function validateTopoloActionInput(schema: Record<string, unknown>, input: unknown): TopoloActionValidationResult;
44
+
34
45
  interface TopoloClientOptions {
35
46
  credential: TopoloCredential;
36
47
  agent: AgentIdentity;
@@ -135,6 +146,27 @@ interface TopoloApiKeyResourceMetadata {
135
146
  defaultEntitlement: 'enterprise';
136
147
  exceptionPolicy: 'app_or_organization';
137
148
  }
149
+ interface TopoloBindableResource {
150
+ resourceType: string;
151
+ resourceId: string;
152
+ label: string | null;
153
+ slug: string | null;
154
+ status: string | null;
155
+ organizationId: string | null;
156
+ metadata: Record<string, unknown>;
157
+ }
158
+ interface TopoloBindableResourceCatalog {
159
+ application: {
160
+ appId: string;
161
+ slug: string | null;
162
+ name: string | null;
163
+ };
164
+ organizationId: string | null;
165
+ resources: TopoloBindableResource[];
166
+ resourceTypes: TopoloApiKeyResourceMetadata[];
167
+ syncError: string | null;
168
+ source: 'api_key_binding' | 'auth_catalog';
169
+ }
138
170
  interface TopoloActionCatalogEntry {
139
171
  actionId: string;
140
172
  target: string | null;
@@ -154,6 +186,7 @@ interface TopoloActionCatalogEntry {
154
186
  authorizationMode?: 'static' | 'runtime';
155
187
  inputSchema: Record<string, unknown>;
156
188
  outputSchema: Record<string, unknown>;
189
+ agentContract?: TopoloActionAgentContract;
157
190
  readOnly: boolean;
158
191
  destructive: boolean;
159
192
  requiresConfirmation: boolean;
@@ -162,6 +195,51 @@ interface TopoloActionCatalogEntry {
162
195
  status: string | null;
163
196
  sourceRevision: string | null;
164
197
  }
198
+ interface TopoloActionAgentContract {
199
+ docsUrl?: string;
200
+ resource?: {
201
+ kind?: string;
202
+ idPath?: string;
203
+ versionPath?: string;
204
+ };
205
+ effects?: string[];
206
+ errors?: Array<{
207
+ status?: number;
208
+ code?: string;
209
+ recovery?: string;
210
+ }>;
211
+ verify?: string[];
212
+ rollbackActionId?: string;
213
+ nextActionIds?: string[];
214
+ examples?: Array<{
215
+ title?: string;
216
+ description?: string;
217
+ input?: Record<string, unknown>;
218
+ }>;
219
+ [key: string]: unknown;
220
+ }
221
+ interface TopoloActionPlan {
222
+ action: TopoloActionCatalogEntry;
223
+ validation: TopoloActionValidationResult;
224
+ confirmationRequired: boolean;
225
+ confirmationProvided: boolean;
226
+ executable: boolean;
227
+ request: {
228
+ method: TopoloActionCatalogEntry['method'];
229
+ service: string;
230
+ apiBaseUrl: string | null;
231
+ path: string;
232
+ query?: Record<string, string | number | boolean>;
233
+ body?: unknown;
234
+ resource?: {
235
+ resourceType: string;
236
+ resourceId: string;
237
+ };
238
+ } | null;
239
+ verification: string[];
240
+ rollbackActionId: string | null;
241
+ nextActionIds: string[];
242
+ }
165
243
  interface TopoloCatalogPage {
166
244
  nextCursor: string | null;
167
245
  hasMore: boolean;
@@ -245,6 +323,7 @@ declare class TopoloClient {
245
323
  /** @deprecated Prefer searchServices() so callers retain the continuation cursor. */
246
324
  listServices(options?: TopoloCatalogSearchOptions): Promise<TopoloServiceCatalogEntry[]>;
247
325
  getService(application: string): Promise<TopoloServiceCatalogEntry>;
326
+ listBindableResources(application: string): Promise<TopoloBindableResourceCatalog>;
248
327
  /**
249
328
  * List callable actions from the live registry-canonical catalog (definitions
250
329
  * from the Catalog registry, scoping from Auth). The response is scoped to the
@@ -267,6 +346,17 @@ declare class TopoloClient {
267
346
  resourceId: string;
268
347
  };
269
348
  }): Promise<T>;
349
+ validateActionInput(action: string, input?: Record<string, unknown>): Promise<{
350
+ action: TopoloActionCatalogEntry;
351
+ validation: TopoloActionValidationResult;
352
+ }>;
353
+ planAction(action: string, input?: Record<string, unknown>, options?: {
354
+ confirm?: boolean;
355
+ resource?: {
356
+ resourceType: string;
357
+ resourceId: string;
358
+ };
359
+ }): Promise<TopoloActionPlan>;
270
360
  readAction<T = unknown>(action: string, input?: Record<string, unknown>, options?: {
271
361
  resource?: {
272
362
  resourceType: string;
@@ -305,6 +395,16 @@ interface CredentialIntrospection {
305
395
  slug: string;
306
396
  name: string;
307
397
  } | null;
398
+ apiKey: {
399
+ id: string | null;
400
+ name: string | null;
401
+ appId: string | null;
402
+ scopes: string[];
403
+ resourceBindings: Array<{
404
+ resourceType: string;
405
+ resourceId: string;
406
+ }>;
407
+ } | null;
308
408
  }
309
409
 
310
410
  declare const ACTION_CATALOG_DIGEST_ALGORITHM: "sha256-v1";
@@ -2192,4 +2292,4 @@ declare function createTopolo(options: TopoloClientOptions): {
2192
2292
  };
2193
2293
  type Topolo = ReturnType<typeof createTopolo>;
2194
2294
 
2195
- export { ACTION_CATALOG_DIGEST_ALGORITHM, APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, 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_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, 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, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, requirementsForApplication, resolveCatalogServiceUrl, resolveServiceUrl, validateTopoloWidgetResponse };
2295
+ export { ACTION_CATALOG_DIGEST_ALGORITHM, APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, 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_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, 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, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, requirementsForApplication, resolveCatalogServiceUrl, resolveServiceUrl, validateTopoloActionInput, validateTopoloWidgetResponse };
package/dist/index.d.ts CHANGED
@@ -31,6 +31,17 @@ interface AgentIdentity {
31
31
  agentName?: string;
32
32
  }
33
33
 
34
+ interface TopoloActionValidationIssue {
35
+ path: string;
36
+ code: string;
37
+ message: string;
38
+ }
39
+ interface TopoloActionValidationResult {
40
+ valid: boolean;
41
+ errors: TopoloActionValidationIssue[];
42
+ }
43
+ declare function validateTopoloActionInput(schema: Record<string, unknown>, input: unknown): TopoloActionValidationResult;
44
+
34
45
  interface TopoloClientOptions {
35
46
  credential: TopoloCredential;
36
47
  agent: AgentIdentity;
@@ -135,6 +146,27 @@ interface TopoloApiKeyResourceMetadata {
135
146
  defaultEntitlement: 'enterprise';
136
147
  exceptionPolicy: 'app_or_organization';
137
148
  }
149
+ interface TopoloBindableResource {
150
+ resourceType: string;
151
+ resourceId: string;
152
+ label: string | null;
153
+ slug: string | null;
154
+ status: string | null;
155
+ organizationId: string | null;
156
+ metadata: Record<string, unknown>;
157
+ }
158
+ interface TopoloBindableResourceCatalog {
159
+ application: {
160
+ appId: string;
161
+ slug: string | null;
162
+ name: string | null;
163
+ };
164
+ organizationId: string | null;
165
+ resources: TopoloBindableResource[];
166
+ resourceTypes: TopoloApiKeyResourceMetadata[];
167
+ syncError: string | null;
168
+ source: 'api_key_binding' | 'auth_catalog';
169
+ }
138
170
  interface TopoloActionCatalogEntry {
139
171
  actionId: string;
140
172
  target: string | null;
@@ -154,6 +186,7 @@ interface TopoloActionCatalogEntry {
154
186
  authorizationMode?: 'static' | 'runtime';
155
187
  inputSchema: Record<string, unknown>;
156
188
  outputSchema: Record<string, unknown>;
189
+ agentContract?: TopoloActionAgentContract;
157
190
  readOnly: boolean;
158
191
  destructive: boolean;
159
192
  requiresConfirmation: boolean;
@@ -162,6 +195,51 @@ interface TopoloActionCatalogEntry {
162
195
  status: string | null;
163
196
  sourceRevision: string | null;
164
197
  }
198
+ interface TopoloActionAgentContract {
199
+ docsUrl?: string;
200
+ resource?: {
201
+ kind?: string;
202
+ idPath?: string;
203
+ versionPath?: string;
204
+ };
205
+ effects?: string[];
206
+ errors?: Array<{
207
+ status?: number;
208
+ code?: string;
209
+ recovery?: string;
210
+ }>;
211
+ verify?: string[];
212
+ rollbackActionId?: string;
213
+ nextActionIds?: string[];
214
+ examples?: Array<{
215
+ title?: string;
216
+ description?: string;
217
+ input?: Record<string, unknown>;
218
+ }>;
219
+ [key: string]: unknown;
220
+ }
221
+ interface TopoloActionPlan {
222
+ action: TopoloActionCatalogEntry;
223
+ validation: TopoloActionValidationResult;
224
+ confirmationRequired: boolean;
225
+ confirmationProvided: boolean;
226
+ executable: boolean;
227
+ request: {
228
+ method: TopoloActionCatalogEntry['method'];
229
+ service: string;
230
+ apiBaseUrl: string | null;
231
+ path: string;
232
+ query?: Record<string, string | number | boolean>;
233
+ body?: unknown;
234
+ resource?: {
235
+ resourceType: string;
236
+ resourceId: string;
237
+ };
238
+ } | null;
239
+ verification: string[];
240
+ rollbackActionId: string | null;
241
+ nextActionIds: string[];
242
+ }
165
243
  interface TopoloCatalogPage {
166
244
  nextCursor: string | null;
167
245
  hasMore: boolean;
@@ -245,6 +323,7 @@ declare class TopoloClient {
245
323
  /** @deprecated Prefer searchServices() so callers retain the continuation cursor. */
246
324
  listServices(options?: TopoloCatalogSearchOptions): Promise<TopoloServiceCatalogEntry[]>;
247
325
  getService(application: string): Promise<TopoloServiceCatalogEntry>;
326
+ listBindableResources(application: string): Promise<TopoloBindableResourceCatalog>;
248
327
  /**
249
328
  * List callable actions from the live registry-canonical catalog (definitions
250
329
  * from the Catalog registry, scoping from Auth). The response is scoped to the
@@ -267,6 +346,17 @@ declare class TopoloClient {
267
346
  resourceId: string;
268
347
  };
269
348
  }): Promise<T>;
349
+ validateActionInput(action: string, input?: Record<string, unknown>): Promise<{
350
+ action: TopoloActionCatalogEntry;
351
+ validation: TopoloActionValidationResult;
352
+ }>;
353
+ planAction(action: string, input?: Record<string, unknown>, options?: {
354
+ confirm?: boolean;
355
+ resource?: {
356
+ resourceType: string;
357
+ resourceId: string;
358
+ };
359
+ }): Promise<TopoloActionPlan>;
270
360
  readAction<T = unknown>(action: string, input?: Record<string, unknown>, options?: {
271
361
  resource?: {
272
362
  resourceType: string;
@@ -305,6 +395,16 @@ interface CredentialIntrospection {
305
395
  slug: string;
306
396
  name: string;
307
397
  } | null;
398
+ apiKey: {
399
+ id: string | null;
400
+ name: string | null;
401
+ appId: string | null;
402
+ scopes: string[];
403
+ resourceBindings: Array<{
404
+ resourceType: string;
405
+ resourceId: string;
406
+ }>;
407
+ } | null;
308
408
  }
309
409
 
310
410
  declare const ACTION_CATALOG_DIGEST_ALGORITHM: "sha256-v1";
@@ -2192,4 +2292,4 @@ declare function createTopolo(options: TopoloClientOptions): {
2192
2292
  };
2193
2293
  type Topolo = ReturnType<typeof createTopolo>;
2194
2294
 
2195
- export { ACTION_CATALOG_DIGEST_ALGORITHM, APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, 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_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, 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, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, requirementsForApplication, resolveCatalogServiceUrl, resolveServiceUrl, validateTopoloWidgetResponse };
2295
+ export { ACTION_CATALOG_DIGEST_ALGORITHM, APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, 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_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, 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, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, requirementsForApplication, resolveCatalogServiceUrl, resolveServiceUrl, validateTopoloActionInput, validateTopoloWidgetResponse };