guidinghand 0.1.0

package/dist/esm/index.js

@@ -0,0 +1,262 @@
+// GuidingHand SDK for JavaScript and TypeScript: the /v1 API (https://guidinghand.ai/openapi.json).
+// No dependencies: it uses the platform's fetch and WebCrypto (Node 18+, Deno, Bun, Cloudflare Workers).
+//
+//   import GuidingHand from 'guidinghand';
+//   const gh = new GuidingHand(); // reads GUIDINGHAND_API_KEY
+//   const session = await gh.sessions.create({ agent_id: 'billing' });
+//   // send session.invite_url to the person at the computer, then:
+//   await gh.sessions.waitForConnection(session.session_id);
+//   const task = await gh.tasks.run(session.session_id, { prompt: 'Turn on Dark Mode', onQuestion: async (q) => 'Work', onApproval: async () => true });
+export const VERSION = '0.1.0';
+// ---------- errors ----------
+export class GuidingHandError extends Error {
+    status;
+    type;
+    body;
+    extra;
+    constructor(message, status = 0, type = 'error', body = null) {
+        super(message);
+        this.name = new.target.name;
+        this.status = status;
+        this.type = type;
+        this.body = body;
+        const e = body?.error;
+        this.extra = e ? Object.fromEntries(Object.entries(e).filter(([k]) => k !== 'type' && k !== 'message')) : {};
+    }
+}
+export class InvalidRequestError extends GuidingHandError {
+}
+export class AuthenticationError extends GuidingHandError {
+}
+export class PaymentRequiredError extends GuidingHandError {
+}
+export class PermissionDeniedError extends GuidingHandError {
+}
+export class NotFoundError extends GuidingHandError {
+}
+export class ConflictError extends GuidingHandError {
+}
+export class RateLimitError extends GuidingHandError {
+}
+export class APIError extends GuidingHandError {
+}
+export class APIConnectionError extends GuidingHandError {
+}
+export class TimeoutError extends GuidingHandError {
+}
+export class SessionExpiredError extends GuidingHandError {
+}
+/** A task waits on a question or approval and `run()` got no handler for it. */
+export class NeedsInputError extends GuidingHandError {
+    task;
+    constructor(task) { super(`The task is waiting for ${task.pending?.type === 'approval' ? 'an approval' : 'an answer'}; pass ${task.pending?.type === 'approval' ? 'onApproval' : 'onQuestion'} to run().`, 0, 'needs_input'); this.task = task; }
+}
+export class WebhookVerificationError extends GuidingHandError {
+}
+const BY_STATUS = { 400: InvalidRequestError, 401: AuthenticationError, 402: PaymentRequiredError, 403: PermissionDeniedError, 404: NotFoundError, 409: ConflictError, 413: InvalidRequestError, 429: RateLimitError };
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const env = (k) => (typeof process !== 'undefined' ? process.env?.[k] : undefined);
+export class GuidingHand {
+    baseUrl;
+    agents;
+    sessions;
+    tasks;
+    webhook;
+    apiKey;
+    timeout;
+    maxRetries;
+    fetchImpl;
+    constructor(opts = {}) {
+        const key = opts.apiKey ?? env('GUIDINGHAND_API_KEY');
+        if (!key)
+            throw new AuthenticationError('No API key: pass { apiKey } or set GUIDINGHAND_API_KEY. Make one in the console under Settings → API keys.', 401, 'authentication');
+        this.apiKey = key;
+        this.baseUrl = (opts.baseUrl ?? env('GUIDINGHAND_BASE_URL') ?? 'https://guidinghand.ai').replace(/\/+$/, '');
+        this.timeout = opts.timeout ?? 60_000;
+        this.maxRetries = opts.maxRetries ?? 2;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+        this.agents = new Agents(this);
+        this.sessions = new Sessions(this);
+        this.tasks = new Tasks(this);
+        this.webhook = new WebhookEndpoint(this);
+    }
+    /** @internal */
+    async request(method, path, { query, body, retry, wait = 0, raw } = {}) {
+        const qs = query ? Object.entries(query).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join('&') : '';
+        const url = `${this.baseUrl}/v1${path}${qs ? `?${qs}` : ''}`;
+        const canRetry = retry ?? (method === 'GET' || method === 'DELETE');
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.fetchImpl(url, {
+                    method,
+                    headers: { Authorization: `Bearer ${this.apiKey}`, 'User-Agent': `guidinghand-js/${VERSION}`, ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}) },
+                    body: body !== undefined ? JSON.stringify(body) : undefined,
+                    signal: AbortSignal.timeout(this.timeout + wait),
+                });
+            }
+            catch (e) {
+                if (canRetry && attempt < this.maxRetries) {
+                    await sleep(500 * 2 ** attempt);
+                    continue;
+                }
+                const timedOut = e?.name === 'TimeoutError';
+                throw timedOut ? new TimeoutError(`No answer from ${this.baseUrl} in ${Math.round((this.timeout + wait) / 1000)} s.`, 0, 'timeout') : new APIConnectionError(`Couldn’t reach ${this.baseUrl}: ${e?.message ?? e}`, 0, 'connection');
+            }
+            if (res.ok)
+                return (raw ? new Uint8Array(await res.arrayBuffer()) : await res.json());
+            if (canRetry && attempt < this.maxRetries && (res.status === 429 || res.status >= 500)) {
+                const after = Number(res.headers.get('retry-after'));
+                await sleep(Number.isFinite(after) && after > 0 ? after * 1000 : 500 * 2 ** attempt);
+                continue;
+            }
+            const j = await res.json().catch(() => null);
+            const Err = BY_STATUS[res.status] ?? (res.status >= 500 ? APIError : GuidingHandError);
+            throw new Err(j?.error?.message ?? `The server answered ${res.status}.`, res.status, j?.error?.type ?? 'error', j);
+        }
+    }
+    /** @internal Every item of a paged list. */
+    async *pages(path, query) {
+        let cursor;
+        do {
+            const p = await this.request('GET', path, { query: { ...query, limit: 100, cursor } });
+            yield* p.data;
+            cursor = p.has_more ? p.next_cursor : null;
+        } while (cursor);
+    }
+}
+export default GuidingHand;
+class Resource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+}
+const enc = encodeURIComponent;
+class Agents extends Resource {
+    list() { return this.client.request('GET', '/agents'); }
+    create(params) { return this.client.request('POST', '/agents', { body: params }); }
+    retrieve(agentId) { return this.client.request('GET', `/agents/${enc(agentId)}`); }
+    update(agentId, params) { return this.client.request('PATCH', `/agents/${enc(agentId)}`, { body: params }); }
+    delete(agentId) { return this.client.request('DELETE', `/agents/${enc(agentId)}`); }
+}
+class Sessions extends Resource {
+    /** Makes a code and its invite link. Send `invite_url` to the person at the computer. */
+    create(params = {}) { return this.client.request('POST', '/sessions', { body: params }); }
+    list(params = {}) { return this.client.request('GET', '/sessions', { query: params }); }
+    /** Every session, newest first, across pages. */
+    listAll(params = {}) { return this.client.pages('/sessions', params); }
+    retrieve(sessionId) { return this.client.request('GET', `/sessions/${enc(sessionId)}`); }
+    /** Disconnects the computer and deletes the session's tasks and recordings. */
+    delete(sessionId) { return this.client.request('DELETE', `/sessions/${enc(sessionId)}`); }
+    /** Resolves once the person's computer is connected. */
+    async waitForConnection(sessionId, { timeout = 600_000, pollInterval = 3_000 } = {}) {
+        const until = Date.now() + timeout;
+        for (;;) {
+            const s = await this.retrieve(sessionId);
+            if (s.status === 'connected')
+                return s;
+            if (s.status === 'expired')
+                throw new SessionExpiredError(`Session ${sessionId} expired before a computer connected. Make a new one.`, 0, 'session_expired');
+            if (Date.now() + pollInterval > until)
+                throw new TimeoutError(`No computer connected to ${sessionId} within ${Math.round(timeout / 1000)} s.`, 0, 'timeout');
+            await sleep(pollInterval);
+        }
+    }
+}
+class Tasks extends Resource {
+    /** Starts a task on the session's computer (it must be connected). */
+    create(sessionId, params) { return this.client.request('POST', `/sessions/${enc(sessionId)}/tasks`, { body: params, retry: !!params.request_id }); }
+    list(params = {}) { return this.client.request('GET', '/tasks', { query: params }); }
+    listAll(params = {}) { return this.client.pages('/tasks', params); }
+    retrieve(taskId, { include } = {}) { return this.client.request('GET', `/tasks/${enc(taskId)}`, { query: { include: include?.join(',') } }); }
+    /** Events after `after`; with `wait_ms`, waits (long poll) for the next one. */
+    events(taskId, { after = 0, wait_ms = 0 } = {}) {
+        return this.client.request('GET', `/tasks/${enc(taskId)}/events`, { query: { after, wait_ms }, wait: wait_ms });
+    }
+    respond(taskId, params) { return this.client.request('POST', `/tasks/${enc(taskId)}/respond`, { body: params }); }
+    stop(taskId) { return this.client.request('POST', `/tasks/${enc(taskId)}/stop`, { body: {} }); }
+    recording(taskId) { return this.client.request('GET', `/tasks/${enc(taskId)}/recording`); }
+    /** One recorded screen, as PNG bytes. */
+    recordingFrame(taskId, seq) { return this.client.request('GET', `/tasks/${enc(taskId)}/recording/${seq}`, { raw: true }); }
+    /** Every event of a task as it happens, until it's done. `for await (const e of gh.tasks.stream(id))` */
+    async *stream(taskId, { after = 0 } = {}) {
+        for (;;) {
+            const r = await this.events(taskId, { after, wait_ms: 25_000 });
+            for (const e of r.data)
+                yield e;
+            after = r.cursor;
+            if (r.task.done)
+                return r.task;
+        }
+    }
+    /** Starts a task and sees it through: events to onEvent, questions to onQuestion, approvals to onApproval. Resolves with the finished task. */
+    async run(sessionId, { onEvent, onQuestion, onApproval, timeout, ...params }) {
+        let task = await this.create(sessionId, params);
+        const until = timeout ? Date.now() + timeout : Infinity;
+        let after = 0, answered = '';
+        while (!task.done) {
+            if (Date.now() > until) {
+                await this.stop(task.task_id).catch(() => { });
+                throw new TimeoutError(`Task ${task.task_id} took longer than ${Math.round(timeout / 1000)} s; stopped it.`, 0, 'timeout');
+            }
+            const r = await this.events(task.task_id, { after, wait_ms: Math.min(25_000, Math.max(0, until - Date.now())) });
+            task = r.task;
+            after = r.cursor;
+            for (const e of r.data)
+                await onEvent?.(e, task);
+            const p = task.pending;
+            if (!p || task.done)
+                continue;
+            const id = p.type === 'question' ? p.question_id : p.approval_id;
+            if (id === answered)
+                continue; // answered already; the task is picking it up
+            if (p.type === 'question') {
+                if (!onQuestion)
+                    throw new NeedsInputError(task);
+                await this.respond(task.task_id, { question_id: p.question_id, answer: String(await onQuestion(p, task)) });
+            }
+            else {
+                if (!onApproval)
+                    throw new NeedsInputError(task);
+                const d = await onApproval(p, task);
+                const decision = typeof d === 'object' ? d : { decision: d === true || d === 'approve' ? 'approve' : 'deny' };
+                await this.respond(task.task_id, { approval_id: p.approval_id, ...decision });
+            }
+            answered = id;
+        }
+        return task;
+    }
+}
+// ---------- webhooks ----------
+class WebhookEndpoint extends Resource {
+    retrieve() { return this.client.request('GET', '/webhook'); }
+    /** Sets the endpoint. The signing secret is in the response when it's new (or with rotate_secret), never again. */
+    update(params) { return this.client.request('PUT', '/webhook', { body: params }); }
+    delete() { return this.client.request('PUT', '/webhook', { body: { url: null } }); }
+}
+/**
+ * Checks a webhook's GuidingHand-Signature header against the raw request body and your signing secret, and
+ * returns the parsed event. Throws WebhookVerificationError if it doesn't match or is older than `tolerance` s.
+ */
+export async function verifyWebhook(payload, signatureHeader, secret, { tolerance = 300 } = {}) {
+    const fail = (m) => new WebhookVerificationError(m, 400, 'webhook_verification');
+    const parts = Object.fromEntries(String(signatureHeader ?? '').split(',').map((kv) => kv.trim().split('=')));
+    const t = Number(parts.t), v1 = parts.v1;
+    if (!t || !v1)
+        throw fail('Missing or malformed GuidingHand-Signature header.');
+    if (Math.abs(Date.now() / 1000 - t) > tolerance)
+        throw fail('The webhook’s timestamp is too old.');
+    const body = typeof payload === 'string' ? payload : new TextDecoder().decode(payload);
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${t}.${body}`)));
+    const want = [...mac].map((b) => b.toString(16).padStart(2, '0')).join('');
+    if (want.length !== v1.length)
+        throw fail('The webhook’s signature doesn’t match.');
+    let diff = 0;
+    for (let i = 0; i < want.length; i++)
+        diff |= want.charCodeAt(i) ^ v1.charCodeAt(i);
+    if (diff)
+        throw fail('The webhook’s signature doesn’t match.');
+    return JSON.parse(body);
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "guidinghand",
+  "version": "0.1.0",
+  "description": "GuidingHand SDK: put an AI agent on your customer's computer with one link. Sessions, tasks, agents, recordings and webhooks.",
+  "license": "MIT",
+  "homepage": "https://guidinghand.ai",
+  "keywords": ["guidinghand", "ai", "agent", "computer-use", "support", "remote-assistance"],
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/esm/index.d.ts", "default": "./dist/esm/index.js" },
+      "require": { "types": "./dist/cjs/index.d.ts", "default": "./dist/cjs/index.js" }
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({ type: 'commonjs' }))\"",
+    "test": "npm run build && node test/e2e.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}