guidinghand 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GuidingHand
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# GuidingHand for JavaScript and TypeScript
+
+Put an AI agent on your customer's Mac or PC with one link. Create a session, send its invite link, and run tasks in plain language: the agent works on their screen, asks when it needs something, and every screen is recorded for replay.
+
+```bash
+npm install guidinghand
+```
+
+No dependencies. Node 18+, Deno, Bun and edge runtimes. Types included. Keep your API key on the server: it isn't meant for browsers.
+
+## Quickstart
+
+```ts
+import GuidingHand from 'guidinghand';
+
+const gh = new GuidingHand(); // reads GUIDINGHAND_API_KEY (Settings → API keys in the console)
+
+// 1. A session: send invite_url to the person at the computer
+const session = await gh.sessions.create({ agent_id: 'default', metadata: { ticket: 'T-123' } });
+console.log('Send this link:', session.invite_url); // https://guidinghand.ai/acme/K7QM-24XP
+
+// 2. Wait for their computer to connect
+await gh.sessions.waitForConnection(session.session_id);
+
+// 3. Run a task, answering the agent's questions and approvals as they come
+const task = await gh.tasks.run(session.session_id, {
+  prompt: 'Turn on Dark Mode',
+  onEvent: (e) => console.log(e.type, e.message),
+  onQuestion: async (q) => 'Work',              // q.question, q.options
+  onApproval: async (a) => a.risk !== 'high',   // true/'approve' or false/'deny'
+});
+
+console.log(task.status, task.result);  // completed "Dark Mode is on."
+console.log('Replay:', task.replay_url);
+```
+
+## Agents
+
+An agent is your configuration: instructions (added under GuidingHand's own rules, which always win), effort and a greeting for the invite page. Every org has a `default` agent.
+
+```ts
+await gh.agents.create({ agent_id: 'billing', name: 'Billing help', instructions: 'Open the Billing app from the Dock.', effort: 'medium', greeting: 'Hi, this is Acme billing.' });
+await gh.agents.update('billing', { effort: 'high' });
+const { data } = await gh.agents.list();
+await gh.agents.delete('billing');
+```
+
+## Sessions
+
+```ts
+const s = await gh.sessions.create({ agent_id: 'billing' });   // s.code, s.invite_url, s.status: 'waiting'
+await gh.sessions.retrieve(s.session_id);                       // status: waiting | connected | disconnected | expired
+for await (const s of gh.sessions.listAll({ agent_id: 'billing' })) console.log(s.code, s.status);
+await gh.sessions.delete(s.session_id);                          // also deletes its tasks and recordings
+```
+
+## Tasks
+
+`run()` is the easy way. Underneath it are:
+
+```ts
+const task = await gh.tasks.create(sessionId, { prompt: 'Install the VPN profile', request_id: 'ticket-123' }); // request_id: safe to retry
+
+for await (const event of gh.tasks.stream(task.task_id)) console.log(event.type, event.message);
+
+const t = await gh.tasks.retrieve(task.task_id, { include: ['events'] });
+if (t.pending?.type === 'question') await gh.tasks.respond(t.task_id, { question_id: t.pending.question_id, answer: 'Work' });
+if (t.pending?.type === 'approval') await gh.tasks.respond(t.task_id, { approval_id: t.pending.approval_id, decision: 'deny', note: 'Not that one' });
+await gh.tasks.stop(t.task_id);
+
+const page = await gh.tasks.list({ status: 'completed', limit: 50 });    // { data, has_more, next_cursor }
+for await (const t of gh.tasks.listAll({ agent_id: 'billing' })) { /* every page */ }
+```
+
+## Recordings
+
+```ts
+const rec = await gh.tasks.recording(taskId);            // rec.frames: [{ seq, t_ms, width, height, url }]
+const png = await gh.tasks.recordingFrame(taskId, 1);   // Uint8Array
+```
+
+The console replays them with the agent's cursor at `task.replay_url`.
+
+## Webhooks
+
+```ts
+const { secret } = await gh.webhook.update({ url: 'https://example.com/guidinghand', events: ['task.completed', 'task.waiting_for_user'] });
+```
+
+Verify each delivery with the raw request body:
+
+```ts
+import { verifyWebhook } from 'guidinghand';
+
+app.post('/guidinghand', express.raw({ type: 'application/json' }), async (req, res) => {
+  const event = await verifyWebhook(req.body, req.header('GuidingHand-Signature'), process.env.GUIDINGHAND_WEBHOOK_SECRET);
+  if (event.type === 'task.completed') console.log(event.data.task.result);
+  res.sendStatus(200);
+});
+```
+
+## Errors
+
+Every error is a `GuidingHandError` with `status`, `type`, `message` and `extra`:
+
+| Class | Status | When |
+|---|---|---|
+| `InvalidRequestError` | 400 | a missing or wrong field |
+| `AuthenticationError` | 401 | no key, or a revoked one |
+| `PaymentRequiredError` | 402 | the org's plan doesn't allow it (free minutes used up) |
+| `PermissionDeniedError` | 403 | your role can't do this |
+| `NotFoundError` | 404 | not in this org |
+| `ConflictError` | 409 | no computer connected, a task already running (`extra.active_task_id`), nothing pending |
+| `RateLimitError` | 429 | too many requests, or the plan's tasks at once |
+| `APIError` | 5xx | our side |
+| `APIConnectionError`, `TimeoutError` | | network |
+| `NeedsInputError` | | `run()` got a question or approval without a handler (`error.task`) |
+| `SessionExpiredError` | | `waitForConnection()` on a code that expired |
+
+Reads, deletes and starts with a `request_id` are retried on connection errors, 429 and 5xx (`maxRetries`, default 2).
+
+## Options
+
+```ts
+new GuidingHand({ apiKey, baseUrl: 'https://dev.guidinghand.ai', timeout: 60_000, maxRetries: 2 });
+```
+
+API reference: https://guidinghand.ai/openapi.json

package/dist/cjs/index.d.ts

@@ -0,0 +1,327 @@
+export declare const VERSION = "0.1.0";
+export type Metadata = Record<string, string>;
+export type Effort = 'low' | 'medium' | 'high' | null;
+export type Agent = {
+    object: 'agent';
+    agent_id: string;
+    name: string;
+    instructions: string;
+    effort: Effort;
+    greeting: string;
+    is_default: boolean;
+    invite_url_template: string;
+    created_at: string | null;
+    updated_at: string | null;
+};
+export type Device = {
+    os: 'mac' | 'windows' | 'linux' | 'unknown';
+    name: string | null;
+    width: number;
+    height: number;
+    app_version: string | null;
+};
+export type SessionStatus = 'waiting' | 'connected' | 'disconnected' | 'expired';
+export type Session = {
+    object: 'session';
+    session_id: string;
+    code: string;
+    agent_id: string;
+    invite_url: string;
+    status: SessionStatus;
+    device: Device | null;
+    metadata: Metadata;
+    created_at: string;
+    paired_at: string | null;
+    last_active_at: string;
+    expires_at: string | null;
+    task_count?: number;
+    latest_task_id?: string | null;
+};
+export type TaskStatus = 'queued' | 'running' | 'waiting_for_user' | 'waiting_for_approval' | 'completed' | 'failed' | 'stopped';
+export type Question = {
+    type: 'question';
+    question_id: string;
+    question: string;
+    options: string[];
+};
+export type Approval = {
+    type: 'approval';
+    approval_id: string;
+    action: string;
+    risk: 'low' | 'medium' | 'high';
+};
+export type EventType = 'started' | 'progress' | 'thinking' | 'action' | 'message' | 'question' | 'answer' | 'approval_required' | 'approved' | 'denied' | 'completed' | 'error' | 'stopped';
+export type TaskEvent = {
+    cursor: number;
+    type: EventType;
+    message: string;
+    ts: string;
+    data?: Record<string, unknown>;
+};
+export type Task = {
+    object: 'task';
+    task_id: string;
+    session_id: string;
+    agent_id: string;
+    status: TaskStatus;
+    done: boolean;
+    prompt: string;
+    result: string | null;
+    error: string | null;
+    pending: Question | Approval | null;
+    cursor?: number;
+    metadata: Metadata;
+    created_at: string;
+    updated_at: string;
+    active_seconds: number;
+    billed_minutes: number | null;
+    replay_url: string | null;
+    recording?: {
+        frames: number;
+    };
+    events?: TaskEvent[];
+    trace?: unknown[];
+    interrupted?: boolean;
+};
+export type Frame = {
+    seq: number;
+    t_ms: number;
+    after_event: number;
+    width: number;
+    height: number;
+    url: string;
+};
+export type Recording = {
+    object: 'recording';
+    task_id: string;
+    frames: Frame[];
+};
+export type WebhookEventType = 'session.connected' | 'session.disconnected' | 'task.started' | 'task.waiting_for_user' | 'task.waiting_for_approval' | 'task.completed' | 'task.failed' | 'task.stopped';
+export type Webhook = {
+    object: 'webhook';
+    url: string | null;
+    events: WebhookEventType[];
+    has_secret: boolean;
+    secret?: string;
+    event_types: WebhookEventType[];
+};
+export type WebhookEvent = {
+    id: string;
+    type: WebhookEventType;
+    created_at: string;
+    org_id: string;
+    data: {
+        task?: Task;
+        session?: Session;
+    };
+};
+export type Page<T> = {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+};
+export type Deleted = {
+    object: string;
+    deleted: true;
+};
+export declare class GuidingHandError extends Error {
+    status: number;
+    type: string;
+    body: unknown;
+    extra: Record<string, unknown>;
+    constructor(message: string, status?: number, type?: string, body?: unknown);
+}
+export declare class InvalidRequestError extends GuidingHandError {
+}
+export declare class AuthenticationError extends GuidingHandError {
+}
+export declare class PaymentRequiredError extends GuidingHandError {
+}
+export declare class PermissionDeniedError extends GuidingHandError {
+}
+export declare class NotFoundError extends GuidingHandError {
+}
+export declare class ConflictError extends GuidingHandError {
+}
+export declare class RateLimitError extends GuidingHandError {
+}
+export declare class APIError extends GuidingHandError {
+}
+export declare class APIConnectionError extends GuidingHandError {
+}
+export declare class TimeoutError extends GuidingHandError {
+}
+export declare class SessionExpiredError extends GuidingHandError {
+}
+/** A task waits on a question or approval and `run()` got no handler for it. */
+export declare class NeedsInputError extends GuidingHandError {
+    task: Task;
+    constructor(task: Task);
+}
+export declare class WebhookVerificationError extends GuidingHandError {
+}
+export type ClientOptions = {
+    /** An org API key (gh_live_…). Defaults to the GUIDINGHAND_API_KEY environment variable. */
+    apiKey?: string;
+    /** Defaults to https://guidinghand.ai (use https://dev.guidinghand.ai for Stripe test mode). */
+    baseUrl?: string;
+    /** Per request, in ms (long polls add their wait). Default 60 000. */
+    timeout?: number;
+    /** Retries on connection errors, 429 and 5xx, for reads and for starts with a request_id. Default 2. */
+    maxRetries?: number;
+    fetch?: typeof fetch;
+};
+type Req = {
+    query?: Record<string, string | number | undefined | null>;
+    body?: unknown;
+    retry?: boolean;
+    wait?: number;
+    raw?: boolean;
+};
+export declare class GuidingHand {
+    readonly baseUrl: string;
+    readonly agents: Agents;
+    readonly sessions: Sessions;
+    readonly tasks: Tasks;
+    readonly webhook: WebhookEndpoint;
+    private apiKey;
+    private timeout;
+    private maxRetries;
+    private fetchImpl;
+    constructor(opts?: ClientOptions);
+    /** @internal */
+    request<T>(method: string, path: string, { query, body, retry, wait, raw }?: Req): Promise<T>;
+    /** @internal Every item of a paged list. */
+    pages<T>(path: string, query: Record<string, string | number | undefined | null>): AsyncGenerator<T>;
+}
+export default GuidingHand;
+declare class Resource {
+    protected client: GuidingHand;
+    constructor(client: GuidingHand);
+}
+export type AgentCreate = {
+    name: string;
+    agent_id?: string;
+    instructions?: string;
+    effort?: Effort;
+    greeting?: string;
+};
+export type AgentUpdate = Partial<Omit<AgentCreate, 'agent_id'>>;
+declare class Agents extends Resource {
+    list(): Promise<Page<Agent>>;
+    create(params: AgentCreate): Promise<Agent>;
+    retrieve(agentId: string): Promise<Agent>;
+    update(agentId: string, params: AgentUpdate): Promise<Agent>;
+    delete(agentId: string): Promise<Deleted>;
+}
+export type SessionCreate = {
+    agent_id?: string;
+    metadata?: Metadata;
+};
+export type SessionList = {
+    agent_id?: string;
+    limit?: number;
+    cursor?: string;
+};
+declare class Sessions extends Resource {
+    /** Makes a code and its invite link. Send `invite_url` to the person at the computer. */
+    create(params?: SessionCreate): Promise<Session & {
+        session_token: string;
+    }>;
+    list(params?: SessionList): Promise<Page<Session>>;
+    /** Every session, newest first, across pages. */
+    listAll(params?: Omit<SessionList, 'limit' | 'cursor'>): AsyncGenerator<Session>;
+    retrieve(sessionId: string): Promise<Session>;
+    /** Disconnects the computer and deletes the session's tasks and recordings. */
+    delete(sessionId: string): Promise<Deleted>;
+    /** Resolves once the person's computer is connected. */
+    waitForConnection(sessionId: string, { timeout, pollInterval }?: {
+        timeout?: number;
+        pollInterval?: number;
+    }): Promise<Session>;
+}
+export type TaskCreate = {
+    prompt: string;
+    agent_id?: string;
+    request_id?: string;
+    metadata?: Metadata;
+};
+export type TaskList = {
+    session_id?: string;
+    agent_id?: string;
+    status?: TaskStatus;
+    limit?: number;
+    cursor?: string;
+};
+export type Respond = {
+    question_id: string;
+    answer: string;
+} | {
+    approval_id: string;
+    decision: 'approve' | 'deny';
+    note?: string;
+};
+export type RunOptions = TaskCreate & {
+    /** Every event, as it happens. */
+    onEvent?: (event: TaskEvent, task: Task) => void | Promise<void>;
+    /** The agent asks something: return the answer. */
+    onQuestion?: (question: Question, task: Task) => string | Promise<string>;
+    /** The agent wants to do something consequential: return true (or 'approve') to let it, false (or 'deny', or { decision, note }) not to. */
+    onApproval?: (approval: Approval, task: Task) => boolean | 'approve' | 'deny' | {
+        decision: 'approve' | 'deny';
+        note?: string;
+    } | Promise<boolean | 'approve' | 'deny' | {
+        decision: 'approve' | 'deny';
+        note?: string;
+    }>;
+    /** Give up (and stop the task) after this long, in ms. */
+    timeout?: number;
+};
+declare class Tasks extends Resource {
+    /** Starts a task on the session's computer (it must be connected). */
+    create(sessionId: string, params: TaskCreate): Promise<Task>;
+    list(params?: TaskList): Promise<Page<Task>>;
+    listAll(params?: Omit<TaskList, 'limit' | 'cursor'>): AsyncGenerator<Task>;
+    retrieve(taskId: string, { include }?: {
+        include?: ('events' | 'trace')[];
+    }): Promise<Task>;
+    /** Events after `after`; with `wait_ms`, waits (long poll) for the next one. */
+    events(taskId: string, { after, wait_ms }?: {
+        after?: number;
+        wait_ms?: number;
+    }): Promise<{
+        data: TaskEvent[];
+        cursor: number;
+        task: Task;
+    }>;
+    respond(taskId: string, params: Respond): Promise<Task>;
+    stop(taskId: string): Promise<Task & {
+        interrupted: boolean;
+    }>;
+    recording(taskId: string): Promise<Recording>;
+    /** One recorded screen, as PNG bytes. */
+    recordingFrame(taskId: string, seq: number): Promise<Uint8Array>;
+    /** Every event of a task as it happens, until it's done. `for await (const e of gh.tasks.stream(id))` */
+    stream(taskId: string, { after }?: {
+        after?: number;
+    }): AsyncGenerator<TaskEvent, Task>;
+    /** Starts a task and sees it through: events to onEvent, questions to onQuestion, approvals to onApproval. Resolves with the finished task. */
+    run(sessionId: string, { onEvent, onQuestion, onApproval, timeout, ...params }: RunOptions): Promise<Task>;
+}
+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. */
+    update(params: {
+        url: string;
+        events?: WebhookEventType[];
+        rotate_secret?: boolean;
+    }): Promise<Webhook>;
+    delete(): Promise<Webhook>;
+}
+/**
+ * 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 declare function verifyWebhook(payload: string | Uint8Array, signatureHeader: string | null | undefined, secret: string, { tolerance }?: {
+    tolerance?: number;
+}): Promise<WebhookEvent>;