@stacklink/sdk 0.2.2 → 0.3.7

package/dist/src/sdk/index.js

@@ -1,6 +1,7 @@
+import { botApiSignaturePayload } from '../domain/bot-contract.js';
 import { materializeStacklinkWorkbenchExecutionResponse, } from '../domain/stacklink-meta-tools.js';
 export { StacklinkMemoryLifecycle, StacklinkMemoryLifecycleError, createStacklinkMemoryLifecycle, serializeCompletedConversationTurn, } from './memory-lifecycle.js';
-export const stacklinkTypeScriptSdkVersion = '0.2.2';
+export const stacklinkTypeScriptSdkVersion = '0.3.7';
 const workbenchReusableRunComparisonWaitMs = 120_000;
 const workbenchReusableRunComparisonPollMs = 1_000;
 export class StacklinkApiError extends Error {
@@ -140,6 +141,39 @@ export async function verifyWebhookSignature(input) {
     }
     return false;
 }
+/** Sign the exact JSON bytes sent to a saved inbound Bot webhook. Reuse requestId when retrying. */
+export async function signBotTriggerRequest(input) {
+    const cryptoImpl = globalThis.crypto ?? (await import('node:crypto')).webcrypto;
+    const timestamp = String(Math.floor((input.now ?? new Date()).getTime() / 1000));
+    const requestId = input.requestId ?? cryptoImpl.randomUUID();
+    const digest = await cryptoImpl.subtle.digest('SHA-256', utf8(input.body));
+    const digestHex = Array.from(new Uint8Array(digest), value => value.toString(16).padStart(2, '0')).join('');
+    const key = await cryptoImpl.subtle.importKey('raw', utf8(input.secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await cryptoImpl.subtle.sign('HMAC', key, utf8(JSON.stringify(['stacklink-trigger-v1', input.triggerId, timestamp, requestId, digestHex])));
+    return { 'content-type': 'application/json', 'stacklink-timestamp': timestamp, 'stacklink-request-id': requestId, 'stacklink-signature': Array.from(new Uint8Array(signature), value => value.toString(16).padStart(2, '0')).join('') };
+}
+/** Verify the original request bytes before using identity. consumeRequestId must atomically reject replays. */
+export async function verifyBotApiRequest(input) {
+    const headers = new Headers(input.headers);
+    const get = (name) => headers.get(`x-stacklink-${name}`) ?? '';
+    const keyId = get('key-id'), timestamp = get('timestamp'), requestId = get('request-id');
+    const key = input.keys[keyId], projectId = get('project'), tenantId = get('tenant'), userId = get('customer');
+    const secret = typeof key === 'string' ? key : key?.secret;
+    const seconds = Number(timestamp), now = Math.floor((input.now ?? new Date()).getTime() / 1000), tolerance = input.toleranceSeconds ?? 300;
+    if (key && typeof key !== 'string' && key.validUntil !== null && (!Number.isFinite(Date.parse(key.validUntil)) || Date.parse(key.validUntil) <= now * 1000))
+        return null;
+    if (typeof secret !== 'string' || !secret || !tenantId || !requestId || projectId !== input.projectId || !Number.isInteger(seconds) || Math.abs(now - seconds) > tolerance)
+        return null;
+    const cryptoImpl = globalThis.crypto ?? (await import('node:crypto')).webcrypto;
+    const digest = await cryptoImpl.subtle.digest('SHA-256', utf8(input.body));
+    const bodySha256 = Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('');
+    const expected = await hmacSha256Base64(secret, botApiSignaturePayload({ method: input.method, url: input.url, requestId, timestamp, keyId, projectId, tenantId, userId, bodySha256 }));
+    if (!constantTimeStringEqual(get('signature'), `v1,${expected}`))
+        return null;
+    if (!await input.consumeRequestId(requestId, new Date((seconds + tolerance) * 1000)))
+        return null;
+    return { tenantId, userId: userId || null, requestId };
+}
 function signatureCandidates(header) {
     const candidates = [];
     for (const entry of header.split(' ')) {
@@ -194,6 +228,8 @@ export class Stacklink {
     discoveryRequests = new Map();
     timeoutMs;
     maxAttempts;
+    bots;
+    approvals;
     webhooks;
     triggers;
     sessions;
@@ -220,6 +256,8 @@ export class Stacklink {
             searchTtlMs: options.cache?.searchTtlMs ?? 120_000,
             maxEntries: options.cache?.maxEntries ?? 500,
         };
+        this.bots = new StacklinkBotsClient(this);
+        this.approvals = new StacklinkApprovalsClient(this);
         this.webhooks = new StacklinkWebhooksClient(this);
         this.triggers = new StacklinkTriggersClient(this);
         this.sessions = new StacklinkSessionsClient(this);
@@ -697,7 +735,7 @@ export class Stacklink {
         const executionKind = accepted.executionKind === 'workbench_code' || accepted.executionKind === 'workbench_bash'
             ? accepted.executionKind
             : undefined;
-        if (!sessionId || !executionId || !executionKind)
+        if (!sessionId || !executionId || !executionKind || accepted.status === 'waiting_for_approval')
             return accepted;
         while (true) {
             const waited = await this.waitForExecution({
@@ -707,7 +745,7 @@ export class Stacklink {
                 waitTimeoutMs: 10_000,
             }, options);
             const execution = isSdkRecord(waited.execution) ? waited.execution : undefined;
-            if (execution && isTerminalSdkExecution(execution)) {
+            if (execution && (isTerminalSdkExecution(execution) || execution.status === 'waiting_for_approval')) {
                 return materializeStacklinkWorkbenchExecutionResponse(accepted, execution);
             }
         }
@@ -745,6 +783,56 @@ export class Stacklink {
             signal: options.signal,
         });
     }
+    async *streamBotEvents(botId, runId, options = {}) {
+        let cursor = options.after ?? '0';
+        const deadline = Date.now() + positiveSdkInteger(options.totalTimeoutMs ?? 300_000, 'totalTimeoutMs');
+        const terminal = (event) => ['run.completed', 'run.failed', 'run.stopped'].includes(String(event.type));
+        while (!options.signal?.aborted) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw new StacklinkApiError('Bot observation timed out. The same run may still be active; resume with the last sequence.', 408, 'sdk_stream_timeout', { runId, after: cursor });
+            try {
+                const response = await this.requestRaw(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}/events/stream`, { headers: { accept: 'text/event-stream', 'Last-Event-ID': cursor }, signal: options.signal, timeoutMs: Math.min(options.timeoutMs ?? 30_000, remaining) });
+                for await (const event of this.readJsonEventStream(response)) {
+                    if (!isSdkRecord(event) || typeof event.sequence !== 'string')
+                        continue;
+                    if (event.runId !== runId)
+                        throw new StacklinkApiError('Bot event belongs to a different run.', 502, 'bot_event_invalid');
+                    if (BigInt(event.sequence) <= BigInt(cursor))
+                        continue;
+                    cursor = event.sequence;
+                    yield event;
+                    if (terminal(event))
+                        return;
+                }
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw options.signal.reason ?? error;
+                const retryable = error instanceof TypeError || (error instanceof Error && ['AbortError', 'TimeoutError'].includes(error.name))
+                    || (error instanceof StacklinkApiError && [408, 429, 502, 503, 504].includes(error.statusCode) && error.code !== 'bot_event_invalid');
+                if (!retryable)
+                    throw error;
+            }
+            // Fetch the durable tail before considering completion. A status read alone
+            // could miss the final text and terminal event that arrived during a disconnect.
+            const page = await this.bots.events(botId, runId, cursor);
+            for (const event of page.events) {
+                if (BigInt(event.sequence) <= BigInt(cursor))
+                    continue;
+                cursor = event.sequence;
+                yield event;
+                if (terminal(event))
+                    return;
+            }
+            if (page.terminal && page.events.length === 0)
+                return;
+            if (page.events.length < 200)
+                await sdkDelay(Math.min(1000, Math.max(1, deadline - Date.now())), options.signal ?? AbortSignal.timeout(Math.max(1, deadline - Date.now())));
+        }
+        if (options.signal?.aborted)
+            throw options.signal.reason;
+    }
     async *streamExecutionEvents(input, options = {}) {
         let afterSequence = input.afterSequence === undefined ? undefined : String(input.afterSequence);
         while (!options.signal?.aborted) {
@@ -1609,29 +1697,35 @@ export class Stacklink {
             }
             return undefined;
         };
-        while (true) {
-            const read = await reader.read();
-            if (read.done)
-                break;
-            buffer += decoder.decode(read.value, { stream: true });
-            let index = buffer.indexOf('\n');
-            while (index >= 0) {
-                const payload = payloadForLine(buffer.slice(0, index));
+        try {
+            while (true) {
+                const read = await reader.read();
+                if (read.done)
+                    break;
+                buffer += decoder.decode(read.value, { stream: true });
+                let index = buffer.indexOf('\n');
+                while (index >= 0) {
+                    const payload = payloadForLine(buffer.slice(0, index));
+                    if (payload !== undefined)
+                        yield payload;
+                    buffer = buffer.slice(index + 1);
+                    index = buffer.indexOf('\n');
+                }
+            }
+            buffer += decoder.decode();
+            if (buffer.length > 0) {
+                const payload = payloadForLine(buffer);
                 if (payload !== undefined)
                     yield payload;
-                buffer = buffer.slice(index + 1);
-                index = buffer.indexOf('\n');
             }
+            const finalPayload = payloadForLine('');
+            if (finalPayload !== undefined)
+                yield finalPayload;
         }
-        buffer += decoder.decode();
-        if (buffer.length > 0) {
-            const payload = payloadForLine(buffer);
-            if (payload !== undefined)
-                yield payload;
+        finally {
+            await reader.cancel().catch(() => undefined);
+            reader.releaseLock();
         }
-        const finalPayload = payloadForLine('');
-        if (finalPayload !== undefined)
-            yield finalPayload;
     }
     requestHeaders(registration, extraHeaders = {}) {
         if (registration) {
@@ -1931,6 +2025,55 @@ export class StacklinkMemoryClient {
         return this.client.request(`/v1/memory/legal-holds/${holdId}/release`, { method: 'POST' });
     }
 }
+export class StacklinkApprovalsClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Server-only access. Identity comes from the authenticated application session. */
+    getCustomerGrant(sessionId) {
+        return this.client.request('/v1/approvals/customer-grant', { query: { sessionId } });
+    }
+    saveCustomerGrant(sessionId, grant) {
+        return this.client.request('/v1/approvals/customer-grant', { method: 'PUT', query: { sessionId }, body: grant });
+    }
+    removeCustomerGrant(sessionId, revision) {
+        return this.client.request('/v1/approvals/customer-grant', { method: 'DELETE', query: { sessionId }, body: { revision } });
+    }
+    list(input) {
+        return this.client.request('/v1/approvals', { query: { ...input } });
+    }
+    get(id, access) {
+        return this.client.request(`/v1/approvals/${encodeURIComponent(id)}`, { query: { ...access } });
+    }
+    /** Decide only after displaying the exact proposal and checking permissions. Never resubmit the original action. */
+    decide(id, access, decision) {
+        return this.client.request(`/v1/approvals/${encodeURIComponent(id)}/decide`, { method: 'POST', query: { ...access }, body: decision });
+    }
+    change(id, access, change) {
+        return this.client.request(`/v1/approvals/${encodeURIComponent(id)}/change`, { method: 'POST', query: { ...access }, body: change });
+    }
+    events(access, after = '0', options = {}) {
+        return this.client.request('/v1/approvals/events', { ...options, query: { ...access, after } });
+    }
+    /** Durable cursor observation. Save each sequence and pass it as `after` when reconnecting. */
+    async *observe(access, options = {}) {
+        let cursor = options.after ?? '0';
+        const deadline = Date.now() + (options.timeoutMs ?? 300_000);
+        const signal = options.signal ?? AbortSignal.timeout(Math.max(1, deadline - Date.now()));
+        while (!signal.aborted && Date.now() < deadline) {
+            const page = await this.events(access, cursor, { signal, timeoutMs: Math.min(15_000, Math.max(1, deadline - Date.now())) });
+            for (const event of page.events) {
+                if (BigInt(event.sequence) <= BigInt(cursor))
+                    continue;
+                cursor = event.sequence;
+                yield event;
+            }
+            if (page.events.length < 100)
+                await sdkDelay(Math.min(1000, Math.max(1, deadline - Date.now())), signal);
+        }
+    }
+}
 export class StacklinkSessionsClient {
     client;
     constructor(client) {
@@ -2988,4 +3131,49 @@ function validateSdkMcpResponse(value, requestId) {
         throw new StacklinkApiError('Stacklink returned an invalid or unrelated MCP response.', 502, 'mcp_response_invalid');
     }
 }
+/** Hosted bots share durable runs across the API, MCP and dashboard. */
+export class StacklinkBotsClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    apis() { return this.client.request('/v1/bots/apis'); }
+    updateApi(apiId, revision, api) { return this.client.request(`/v1/bots/apis/${encodeURIComponent(apiId)}`, { method: 'PATCH', body: { revision, api } }); }
+    deleteApi(apiId) { return this.client.request(`/v1/bots/apis/${encodeURIComponent(apiId)}`, { method: 'DELETE' }); }
+    webhookSecret(botId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/webhook-secret`, { method: 'POST', body: {} }); }
+    triggerWebhook(botId, triggerId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/triggers/${encodeURIComponent(triggerId)}/webhook`, { method: 'POST', body: {} }); }
+    triggerAdmission(botId, triggerId, admissionId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/triggers/${encodeURIComponent(triggerId)}/admissions/${encodeURIComponent(admissionId)}`); }
+    apiSigningKey(botId, apiId, request = { action: 'read' }) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/apis/${encodeURIComponent(apiId)}/signing-key`, { method: 'POST', body: request }); }
+    models() { return this.client.request('/v1/bots/models'); }
+    setCredential(botId, secret) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/credentials`, { method: 'POST', body: { secret } }); }
+    deliveries(botId, runId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}/deliveries`); }
+    retryDelivery(botId, runId, deliveryId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}/deliveries/retry`, { method: 'POST', body: { deliveryId } }); }
+    setCustomerCredential(botId, input) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/credentials`, { method: 'POST', body: input }); }
+    delete(botId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}`, { method: 'DELETE' }); }
+    deleteCustomerData(botId, sessionId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/customer-data/delete`, { method: 'POST', body: { sessionId } }); }
+    setState(botId, input) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/state`, { method: 'POST', body: input }); }
+    list() { return this.client.request('/v1/bots'); }
+    create(name) { return this.client.request('/v1/bots', { method: 'POST', body: { name } }); }
+    get(botId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}`); }
+    update(botId, revision, patch) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}`, { method: 'PATCH', body: { revision, patch } }); }
+    publish(botId, revision, channels) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/publish`, { method: 'POST', body: { revision, channels } }); }
+    run(botId, input) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs`, { method: 'POST', body: { ...input, runId: input.runId ?? globalThis.crypto.randomUUID() } }); }
+    getRun(botId, runId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}`); }
+    /** Observe the same durable run. Returns when finished or when a person must act. */
+    async wait(botId, runId, options = {}) {
+        const deadline = Date.now() + positiveSdkInteger(options.totalTimeoutMs ?? 300_000, 'totalTimeoutMs');
+        while (Date.now() < deadline) {
+            if (options.signal?.aborted)
+                throw options.signal.reason;
+            const run = await this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}`, { signal: options.signal, timeoutMs: Math.min(30_000, deadline - Date.now()) });
+            if (['completed', 'failed', 'stopped', 'cancelled', 'waiting_for_approval', 'waiting_for_connection'].includes(run.status))
+                return run;
+            await sdkDelay(Math.min(1000, Math.max(1, deadline - Date.now())), options.signal ?? AbortSignal.timeout(Math.max(1, deadline - Date.now())));
+        }
+        throw new StacklinkApiError('Bot observation timed out. Continue observing the same run.', 408, 'sdk_run_timeout', { botId, runId });
+    }
+    events(botId, runId, after = '0') { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}/events`, { query: { after } }); }
+    stream(botId, runId, options = {}) { return this.client.streamBotEvents(botId, runId, options); }
+    cancel(botId, runId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}/stop`, { method: 'POST', body: {} }); }
+}
 //# sourceMappingURL=index.js.map