@stacklink/sdk 0.2.2 → 0.3.8

package/dist/src/sdk/index.d.ts

@@ -1,3 +1,7 @@
+import type { Bot, BotPatch, BotRun, BotRunInput, PublishChannels, SavedBotApi, ContextApi, BotApiSigningKey, BotApiSigningKeyRequest } from '../domain/bot-contract.js';
+import type { ApprovalRecord, ApprovalDecision, ApprovalChange, ApprovalListResponse, ApprovalListQuery, CustomerApprovalGrantInput, CustomerApprovalGrantResponse } from '../domain/platform-approval-contract.js';
+export type { ApprovalRecord, ApprovalDecision, ApprovalChange, ApprovalListResponse, ApprovalAudience, ApprovalRequirement, CustomerApprovalGrantInput, CustomerApprovalGrantResponse } from '../domain/platform-approval-contract.js';
+export type { Bot, BotPatch, BotRun, BotRunInput, PublishChannels, SavedBotApi, ContextApi, BotApiSigningKey, BotApiSigningKeyRequest, BotTrigger, BotPreparation, BotRunDisplay, BotReadinessIssue } from '../domain/bot-contract.js';
 import { type StacklinkMetaToolName } from '../domain/stacklink-meta-tools.js';
 import type { ProviderBrandDescriptor } from '../domain/provider-branding.js';
 import type { MemoryContextInput, MemoryConversationTurnInput, MemoryConnectedSourceInput, MemoryConnectedSourcePreviewInput, MemoryExportInput, MemoryGraphQueryInput, MemoryIngestInput, MemoryRichIngestInput, MemoryLegalHoldInput, MemoryPolicyPreviewInput, MemoryProjectPolicyInput, MemoryProjectPolicyUpdateInput, MemorySearchInput, MemorySourceBindingInput, MemorySourceBindingUpdateInput, MemorySourceRemovalInput, MemorySubjectRef } from '../domain/memory-contract.js';
@@ -8,7 +12,7 @@ export type { StacklinkMemoryAvailabilityMode, StacklinkMemoryCaptureController,
 export type StacklinkFetch = typeof fetch;
 export type StacklinkMcpToolName = StacklinkMetaToolName;
 export type StacklinkToolSurfaceName = StacklinkMcpToolName | (string & {});
-export declare const stacklinkTypeScriptSdkVersion = "0.2.2";
+export declare const stacklinkTypeScriptSdkVersion = "0.3.8";
 export declare class StacklinkApiError extends Error {
     readonly statusCode: number;
     readonly code?: string | undefined;
@@ -92,12 +96,14 @@ export interface StacklinkProviderOperation {
     transport: 'rest' | 'graphql' | 'sdk' | 'local' | 'mcp';
     method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | undefined;
     path?: string | undefined;
+    credentialProfileKey?: string | undefined;
     graphqlOperationName?: string | undefined;
     docsUrl?: string | undefined;
-    source: 'official_openapi' | 'official_docs' | 'hand_authored';
+    source: 'official_openapi' | 'official_google_discovery' | 'authenticated_mcp_tools' | 'official_docs' | 'hand_authored';
 }
 export interface StacklinkToolAuthPolicy {
     connectionRequired: boolean;
+    credentialProfileKey?: string | undefined;
     scopeRequirements: Array<{
         all?: string[] | undefined;
         any?: string[] | undefined;
@@ -169,12 +175,15 @@ export interface ProviderRuntime {
     owner: ProviderRuntimeOwner;
     label: string;
     mcp?: {
-        endpointUrl: string;
+        defaultEndpointKey: string;
+        endpoints: Record<string, {
+            endpointUrl: string;
+            sourceUrl: string;
+        }>;
         transport: ProviderMcpTransport;
         auth: {
             type: ProviderMcpAuthType;
         };
-        sourceUrl: string;
         importPolicy: ProviderMcpImportPolicy;
         allowlisted: boolean;
         identity?: {
@@ -609,7 +618,7 @@ export interface CreateTriggerSubscriptionInput {
     tenantId: string;
     accountId?: string | undefined;
     triggerTypeId: string;
-    deliveryMode?: 'webhook' | 'polling' | undefined;
+    deliveryMode?: 'webhook' | 'polling' | 'stream' | undefined;
     config?: Record<string, unknown> | undefined;
     idempotencyKey?: string | undefined;
 }
@@ -912,7 +921,7 @@ export interface WorkbenchRuntimeDiagnostics {
     exitCode?: number | undefined;
     error?: unknown;
 }
-export type WorkbenchExecutionStatus = 'queued' | 'started' | 'running' | 'cancel_requested' | 'completed' | 'failed' | 'cancelled' | 'timed_out';
+export type WorkbenchExecutionStatus = 'waiting_for_approval' | 'queued' | 'started' | 'running' | 'cancel_requested' | 'completed' | 'failed' | 'cancelled' | 'timed_out';
 export interface WorkbenchExecutionLog {
     id: string;
     executionId?: string | undefined;
@@ -1003,6 +1012,9 @@ export interface WorkbenchOutputPreview {
     preview: string;
 }
 export interface WorkbenchExecutionResponse {
+    approvalRequestId?: string | undefined;
+    executed?: boolean | undefined;
+    nextAction?: 'wait_for_approval' | undefined;
     workbenchSession: WorkbenchSession;
     executionKind: 'workbench_code' | 'workbench_bash';
     executionId: string;
@@ -1338,6 +1350,12 @@ export interface StacklinkAgentSearchResponse {
             capability: string;
             risk: string;
             connectionStatus: string;
+            credentialProfile?: {
+                key: string;
+                status: 'available' | 'required';
+                eligibleAccountIds: string[];
+                missingAccountIds: string[];
+            } | undefined;
             contractRef?: string | undefined;
         }>;
         nextAction?: {
@@ -1941,6 +1959,33 @@ export interface GstNoticeRuleResponse extends GstRateLookupResponse {
 export interface GstAppealStageRuleResponse extends GstRateLookupResponse {
 }
 export declare function verifyWebhookSignature(input: StacklinkWebhookSignatureInput): Promise<boolean>;
+/** Sign the exact JSON bytes sent to a saved inbound Bot webhook. Reuse requestId when retrying. */
+export declare function signBotTriggerRequest(input: {
+    triggerId: string;
+    secret: string;
+    body: string;
+    requestId?: string;
+    now?: Date;
+}): Promise<Record<string, string>>;
+/** Verify the original request bytes before using identity. consumeRequestId must atomically reject replays. */
+export declare function verifyBotApiRequest(input: {
+    method: string;
+    url: string;
+    body: string;
+    headers: ConstructorParameters<typeof Headers>[0];
+    projectId: string;
+    keys: Record<string, string | {
+        secret: string;
+        validUntil: string | null;
+    }>;
+    consumeRequestId: (id: string, expiresAt: Date) => boolean | Promise<boolean>;
+    now?: Date;
+    toleranceSeconds?: number;
+}): Promise<{
+    tenantId: string;
+    userId: string | null;
+    requestId: string;
+} | null>;
 export declare class Stacklink {
     private readonly apiKey;
     private readonly registrationKey;
@@ -1951,6 +1996,8 @@ export declare class Stacklink {
     private readonly discoveryRequests;
     private readonly timeoutMs;
     private readonly maxAttempts;
+    readonly bots: StacklinkBotsClient;
+    readonly approvals: StacklinkApprovalsClient;
     readonly webhooks: StacklinkWebhooksClient;
     readonly triggers: StacklinkTriggersClient;
     readonly sessions: StacklinkSessionsClient;
@@ -2376,6 +2423,14 @@ export declare class Stacklink {
         hasMore: boolean;
         nextCursor: string | null;
     }>;
+    streamBotEvents(botId: string, runId: string, options?: StacklinkRequestOptions & {
+        after?: string;
+        totalTimeoutMs?: number;
+    }): AsyncGenerator<Record<string, unknown> | {
+        sequence: string;
+        type: string;
+        payload: unknown;
+    }, void, unknown>;
     streamExecutionEvents(input: {
         sessionId: string;
         executionKind: StacklinkExecutionKind;
@@ -2419,6 +2474,20 @@ export declare class Stacklink {
     getConnectedAccount(accountId: string): Promise<{
         account: ConnectedAccount;
     }>;
+    setConnectedAccountCredentialProfile(accountId: string, profileKey: string, credentials: Record<string, string>): Promise<{
+        profile: {
+            profileKey: string;
+            version: number;
+            status: string;
+        };
+    }>;
+    removeConnectedAccountCredentialProfile(accountId: string, profileKey: string): Promise<{
+        profile: {
+            profileKey: string;
+            removed: boolean;
+            providerGrantRevoked: boolean;
+        };
+    }>;
     listConnectedAccountTools(accountId: string, input: {
         includePlanned?: boolean | undefined;
         toolKeys: string[];
@@ -2935,6 +3004,45 @@ export declare class StacklinkMemoryClient {
     createLegalHold(input: MemoryLegalHoldInput): Promise<JsonRecord>;
     releaseLegalHold(holdId: string): Promise<JsonRecord>;
 }
+export interface StacklinkApprovalAccess {
+    sessionId: string;
+    asCustomer?: boolean;
+}
+export interface StacklinkApprovalEvent {
+    sequence: string;
+    approvalId: string;
+    type: 'approval.request.updated';
+    data: {
+        revision: number;
+        status: string;
+        requirements: unknown[];
+        denialReason: string | null;
+    };
+    occurredAt: string;
+}
+export declare class StacklinkApprovalsClient {
+    private readonly client;
+    constructor(client: Stacklink);
+    /** Server-only access. Identity comes from the authenticated application session. */
+    getCustomerGrant(sessionId: string): Promise<CustomerApprovalGrantResponse>;
+    saveCustomerGrant(sessionId: string, grant: CustomerApprovalGrantInput): Promise<CustomerApprovalGrantResponse>;
+    removeCustomerGrant(sessionId: string, revision: number): Promise<CustomerApprovalGrantResponse>;
+    list(input: StacklinkApprovalAccess & Partial<ApprovalListQuery>): Promise<ApprovalListResponse>;
+    get(id: string, access: StacklinkApprovalAccess): Promise<ApprovalRecord>;
+    /** Decide only after displaying the exact proposal and checking permissions. Never resubmit the original action. */
+    decide(id: string, access: StacklinkApprovalAccess, decision: ApprovalDecision): Promise<ApprovalRecord>;
+    change(id: string, access: StacklinkApprovalAccess, change: ApprovalChange): Promise<ApprovalRecord>;
+    events(access: StacklinkApprovalAccess, after?: string, options?: StacklinkRequestOptions): Promise<{
+        events: StacklinkApprovalEvent[];
+        nextCursor: string;
+    }>;
+    /** Durable cursor observation. Save each sequence and pass it as `after` when reconnecting. */
+    observe(access: StacklinkApprovalAccess, options?: {
+        after?: string;
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): AsyncGenerator<StacklinkApprovalEvent>;
+}
 export declare class StacklinkSessionsClient {
     private readonly client;
     constructor(client: Stacklink);
@@ -3578,4 +3686,115 @@ export declare class StacklinkConnectionRequest {
     };
     waitForConnection(timeoutMs?: number, intervalMs?: number): Promise<ConnectedAccount | undefined>;
 }
+/** Hosted bots share durable runs across the API, MCP and dashboard. */
+export declare class StacklinkBotsClient {
+    private readonly client;
+    constructor(client: Stacklink);
+    apis(): Promise<{
+        apis: SavedBotApi[];
+    }>;
+    updateApi(apiId: string, revision: number, api: ContextApi): Promise<SavedBotApi>;
+    deleteApi(apiId: string): Promise<{
+        deleted: boolean;
+    }>;
+    webhookSecret(botId: string): Promise<{
+        signingSecret: string;
+    }>;
+    triggerWebhook(botId: string, triggerId: string): Promise<{
+        url: string;
+        signingSecret: string;
+        signatureVersion: string;
+        maxAgeSeconds: number;
+    }>;
+    triggerAdmission(botId: string, triggerId: string, admissionId: string): Promise<{
+        admissionId: string;
+        status: string;
+        runId: string | null;
+        result: unknown;
+        error: unknown;
+    }>;
+    apiSigningKey(botId: string, apiId: string, request?: BotApiSigningKeyRequest): Promise<BotApiSigningKey>;
+    models(): Promise<{
+        models: import("../domain/bot-contract.js").ModelOption[];
+        defaultModel: string;
+    }>;
+    setCredential(botId: string, secret: string): Promise<{
+        id: string;
+    }>;
+    deliveries(botId: string, runId: string): Promise<{
+        deliveries: Array<{
+            id: string;
+            status: string;
+            attemptCount: number;
+            nextAttemptAt: string | null;
+            failureReason: string | null;
+        }>;
+    }>;
+    retryDelivery(botId: string, runId: string, deliveryId: string): Promise<{
+        queued: boolean;
+    }>;
+    setCustomerCredential(botId: string, input: {
+        apiId: string;
+        sessionId: string;
+        secret: string;
+    }): Promise<{
+        id: string;
+    }>;
+    delete(botId: string): Promise<{
+        deleted: boolean;
+    }>;
+    deleteCustomerData(botId: string, sessionId: string): Promise<{
+        deleted: boolean;
+        conversations: number;
+        knowledgeSources: number;
+        workspaces: number;
+        sharedMemory: "unchanged";
+        sharedApiCredentials: "unchanged";
+    }>;
+    setState(botId: string, input: {
+        state: 'on' | 'paused';
+        pauseFor?: '1h' | 'tomorrow' | 'manual';
+        reason?: string;
+    }): Promise<Bot>;
+    list(): Promise<{
+        bots: Array<{
+            id: string;
+            name: string;
+            status: string;
+        }>;
+    }>;
+    create(name: string): Promise<Bot>;
+    get(botId: string): Promise<Bot>;
+    update(botId: string, revision: number, patch: BotPatch): Promise<Bot>;
+    publish(botId: string, revision: number, channels: PublishChannels): Promise<{
+        botId: string;
+        publishedAt: string;
+    }>;
+    run(botId: string, input: BotRunInput & {
+        sessionId: string;
+    }): Promise<BotRun>;
+    getRun(botId: string, runId: string): Promise<BotRun>;
+    /** Observe the same durable run. Returns when finished or when a person must act. */
+    wait(botId: string, runId: string, options?: {
+        totalTimeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<BotRun>;
+    events(botId: string, runId: string, after?: string): Promise<{
+        events: Array<{
+            sequence: string;
+            type: string;
+            payload: unknown;
+        }>;
+        terminal: boolean;
+    }>;
+    stream(botId: string, runId: string, options?: StacklinkRequestOptions & {
+        after?: string;
+        totalTimeoutMs?: number;
+    }): AsyncGenerator<Record<string, unknown> | {
+        sequence: string;
+        type: string;
+        payload: unknown;
+    }, void, unknown>;
+    cancel(botId: string, runId: string): Promise<BotRun>;
+}
 //# sourceMappingURL=index.d.ts.map