guidinghand 0.1.0 → 0.1.1

package/dist/cjs/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.1";
 export type Metadata = Record<string, string>;
 export type Effort = 'low' | 'medium' | 'high' | null;
 export type Agent = {
@@ -310,9 +310,13 @@ declare class Tasks extends Resource {
 }
 declare class WebhookEndpoint extends Resource {
     retrieve(): Promise<Webhook>;
-    /** Sets the endpoint. The signing secret is in the response when it's new (or with rotate_secret), never again. */
+    /**
+     * Sets the endpoint. Only the fields you pass change: without url the endpoint stays, without events the
+     * filter stays, so { rotate_secret: true } alone makes a new secret. The signing secret is in the response
+     * when it's new (or rotated), never again.
+     */
     update(params: {
-        url: string;
+        url?: string;
         events?: WebhookEventType[];
         rotate_secret?: boolean;
     }): Promise<Webhook>;

package/dist/cjs/index.js

@@ -11,7 +11,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GuidingHand = exports.WebhookVerificationError = exports.NeedsInputError = exports.SessionExpiredError = exports.TimeoutError = exports.APIConnectionError = exports.APIError = exports.RateLimitError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.PaymentRequiredError = exports.AuthenticationError = exports.InvalidRequestError = exports.GuidingHandError = exports.VERSION = void 0;
 exports.verifyWebhook = verifyWebhook;
-exports.VERSION = '0.1.0';
+exports.VERSION = '0.1.1';
 // ---------- errors ----------
 class GuidingHandError extends Error {
     status;
@@ -123,6 +123,9 @@ class GuidingHand {
             }
             if (res.ok)
                 return (raw ? new Uint8Array(await res.arrayBuffer()) : await res.json());
+            // A retried delete that finds it gone: the first attempt did it (its answer was lost on the way back).
+            if (method === 'DELETE' && attempt > 0 && res.status === 404)
+                return { object: path.split('/')[1]?.replace(/s$/, '') ?? 'object', deleted: true };
             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);
@@ -216,7 +219,9 @@ class Tasks extends Resource {
         let after = 0, answered = '';
         while (!task.done) {
             if (Date.now() > until) {
-                await this.stop(task.task_id).catch(() => { });
+                const stopped = await this.stop(task.task_id).catch(() => null);
+                if (stopped && stopped.done && !stopped.interrupted)
+                    return stopped; // it finished just as time ran out
                 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())) });
@@ -230,17 +235,24 @@ class Tasks extends Resource {
             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)) });
+            try {
+                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 = d && typeof d === 'object' ? d : { decision: d === true || d === 'approve' ? 'approve' : 'deny' };
+                    await this.respond(task.task_id, { approval_id: p.approval_id, ...decision });
+                }
             }
-            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 });
+            catch (e) {
+                // Answered from somewhere else (the console, another process) or the task ended meanwhile: keep following.
+                if (!(e instanceof ConflictError))
+                    throw e;
             }
             answered = id;
         }
@@ -250,7 +262,11 @@ class Tasks extends Resource {
 // ---------- 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. */
+    /**
+     * Sets the endpoint. Only the fields you pass change: without url the endpoint stays, without events the
+     * filter stays, so { rotate_secret: true } alone makes a new secret. The signing secret is in the response
+     * when it's new (or rotated), never again.
+     */
     update(params) { return this.client.request('PUT', '/webhook', { body: params }); }
     delete() { return this.client.request('PUT', '/webhook', { body: { url: null } }); }
 }
@@ -267,8 +283,10 @@ async function verifyWebhook(payload, signatureHeader, secret, { tolerance = 300
     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}`)));
+    // Node 18 has WebCrypto at node:crypto but not as a global; Node 20+, Deno, Bun and Workers have both.
+    const subtle = globalThis.crypto?.subtle ?? (await Promise.resolve(`${'node:crypto'}`).then(s => require(s))).webcrypto.subtle;
+    const key = await subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const mac = new Uint8Array(await 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.');

package/dist/esm/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.1";
 export type Metadata = Record<string, string>;
 export type Effort = 'low' | 'medium' | 'high' | null;
 export type Agent = {
@@ -310,9 +310,13 @@ declare class Tasks extends Resource {
 }
 declare class WebhookEndpoint extends Resource {
     retrieve(): Promise<Webhook>;
-    /** Sets the endpoint. The signing secret is in the response when it's new (or with rotate_secret), never again. */
+    /**
+     * Sets the endpoint. Only the fields you pass change: without url the endpoint stays, without events the
+     * filter stays, so { rotate_secret: true } alone makes a new secret. The signing secret is in the response
+     * when it's new (or rotated), never again.
+     */
     update(params: {
-        url: string;
+        url?: string;
         events?: WebhookEventType[];
         rotate_secret?: boolean;
     }): Promise<Webhook>;

package/dist/esm/index.js

@@ -7,7 +7,7 @@
 //   // 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';
+export const VERSION = '0.1.1';
 // ---------- errors ----------
 export class GuidingHandError extends Error {
     status;
@@ -105,6 +105,9 @@ export class GuidingHand {
             }
             if (res.ok)
                 return (raw ? new Uint8Array(await res.arrayBuffer()) : await res.json());
+            // A retried delete that finds it gone: the first attempt did it (its answer was lost on the way back).
+            if (method === 'DELETE' && attempt > 0 && res.status === 404)
+                return { object: path.split('/')[1]?.replace(/s$/, '') ?? 'object', deleted: true };
             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);
@@ -197,7 +200,9 @@ class Tasks extends Resource {
         let after = 0, answered = '';
         while (!task.done) {
             if (Date.now() > until) {
-                await this.stop(task.task_id).catch(() => { });
+                const stopped = await this.stop(task.task_id).catch(() => null);
+                if (stopped && stopped.done && !stopped.interrupted)
+                    return stopped; // it finished just as time ran out
                 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())) });
@@ -211,17 +216,24 @@ class Tasks extends Resource {
             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)) });
+            try {
+                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 = d && typeof d === 'object' ? d : { decision: d === true || d === 'approve' ? 'approve' : 'deny' };
+                    await this.respond(task.task_id, { approval_id: p.approval_id, ...decision });
+                }
             }
-            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 });
+            catch (e) {
+                // Answered from somewhere else (the console, another process) or the task ended meanwhile: keep following.
+                if (!(e instanceof ConflictError))
+                    throw e;
             }
             answered = id;
         }
@@ -231,7 +243,11 @@ class Tasks extends Resource {
 // ---------- 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. */
+    /**
+     * Sets the endpoint. Only the fields you pass change: without url the endpoint stays, without events the
+     * filter stays, so { rotate_secret: true } alone makes a new secret. The signing secret is in the response
+     * when it's new (or rotated), never again.
+     */
     update(params) { return this.client.request('PUT', '/webhook', { body: params }); }
     delete() { return this.client.request('PUT', '/webhook', { body: { url: null } }); }
 }
@@ -248,8 +264,10 @@ export async function verifyWebhook(payload, signatureHeader, secret, { toleranc
     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}`)));
+    // Node 18 has WebCrypto at node:crypto but not as a global; Node 20+, Deno, Bun and Workers have both.
+    const subtle = globalThis.crypto?.subtle ?? (await import('node:crypto')).webcrypto.subtle;
+    const key = await subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const mac = new Uint8Array(await 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.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guidinghand",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",