@agent-api/sdk 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog — @agent-api/sdk
 
+## 1.1.1
+
+### Added
+
+- Browser/device login helpers for CLI and desktop integrations: `client.auth.startDeviceAuth()`, `client.auth.pollDeviceAuth()`, and `client.auth.waitForDeviceAuth()`.
+- Convenience methods on `AgentAPI`: `startDeviceAuth()`, `pollDeviceAuth()`, and `waitForDeviceAuth()`.
+- `DeviceAuthFlowError` for expired, consumed, or timed-out device login flows.
+
 ## 1.1.0
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 Production JavaScript/TypeScript SDK for the Managed Agent API.
 
-**Published on npm:** [`@agent-api/sdk`](https://www.npmjs.com/package/@agent-api/sdk) (v1.0.8)
+**Published on npm:** [`@agent-api/sdk`](https://www.npmjs.com/package/@agent-api/sdk) (v1.1.1)
 
 ## Install
 
@@ -46,7 +46,7 @@ src/
   errors.ts           # Typed error hierarchy + retry helpers
   pagination.ts       # Cursor pagination utilities
   streaming.ts        # SSE parser
-  resources/          # responses, models, presets, tools, volumes, skills
+  resources/          # auth, responses, models, presets, tools, volumes, skills
   types/              # Request/response TypeScript types
   internal/http.ts    # Retries, timeouts, User-Agent
 ```
@@ -61,6 +61,25 @@ src/
 | `client.tools` | `list` |
 | `client.volumes` | `list`, `create`, `retrieve`, `update`, `delete`, `listEntries`, `searchEntries`, `readFile`, `writeFile`, `deletePath`, `reconcileUsage`, `createDirectory`, `downloadArchive`, `summarize`, `readLines`, `patchLines`, `grep` |
 | `client.skills` | `list`, `create`, `discover`, `focus`, `createDev`, `updateFile`, `retrieve`, `update`, `archive`, `delete`, `diff`, `acceptDev`, `discardDev`, `exportArchive`, `importArchive`, `pushDirectory`, `pullDirectory`, `listFiles`, `readFile`, `writeFile`, `deleteFile` |
+| `client.auth` | `startDeviceAuth`, `pollDeviceAuth`, `waitForDeviceAuth` |
+
+## Browser Device Login
+
+CLI and desktop apps can use browser login without handling user passwords or static API keys.
+
+```typescript
+const challenge = await client.auth.startDeviceAuth({ client_name: "Agent CLI" });
+console.log(`Open ${challenge.verification_uri_complete}`);
+
+const session = await client.auth.waitForDeviceAuth({
+  device_code: challenge.device_code,
+  interval_seconds: challenge.interval_seconds,
+});
+
+console.log(session.access_token);
+```
+
+The SDK returns URLs and polling helpers only. Opening the browser belongs to the CLI, Electron, Tauri, or native host app.
 
 ## Durable Volumes
 

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import { AuthResource } from "./resources/auth.js";
 import { ModelsResource } from "./resources/models.js";
 import { PresetsResource } from "./resources/presets.js";
 import { ResponsesResource } from "./resources/responses.js";
@@ -23,7 +24,11 @@ export declare class AgentAPI {
     readonly tools: ToolsResource;
     readonly volumes: VolumesResource;
     readonly skills: SkillsResource;
+    readonly auth: AuthResource;
     private readonly http;
     constructor(options?: ClientOptions);
+    startDeviceAuth: (...args: Parameters<AuthResource["startDeviceAuth"]>) => Promise<import("./index.js").DeviceAuthStart>;
+    pollDeviceAuth: (...args: Parameters<AuthResource["pollDeviceAuth"]>) => Promise<import("./index.js").DeviceAuthPollResult>;
+    waitForDeviceAuth: (...args: Parameters<AuthResource["waitForDeviceAuth"]>) => Promise<import("./index.js").ApprovedDeviceAuth>;
 }
 export { VERSION };

package/dist/client.js

@@ -1,6 +1,7 @@
 import { APIConnectionError } from "./errors.js";
 import { readEnv } from "./internal/env.js";
 import { HTTPClient } from "./internal/http.js";
+import { AuthResource } from "./resources/auth.js";
 import { ModelsResource } from "./resources/models.js";
 import { PresetsResource } from "./resources/presets.js";
 import { ResponsesResource } from "./resources/responses.js";
@@ -25,6 +26,7 @@ export class AgentAPI {
     tools;
     volumes;
     skills;
+    auth;
     http;
     constructor(options = {}) {
         this.apiKey = options.apiKey ?? readEnv("AGENT_API_KEY");
@@ -53,6 +55,10 @@ export class AgentAPI {
         this.tools = new ToolsResource(this.http);
         this.volumes = new VolumesResource(this.http);
         this.skills = new SkillsResource(this.http);
+        this.auth = new AuthResource(this.http);
     }
+    startDeviceAuth = (...args) => this.auth.startDeviceAuth(...args);
+    pollDeviceAuth = (...args) => this.auth.pollDeviceAuth(...args);
+    waitForDeviceAuth = (...args) => this.auth.waitForDeviceAuth(...args);
 }
 export { VERSION };

package/dist/index.d.ts

@@ -7,3 +7,4 @@ export { functionCallOutputInput, pendingFunctionCalls, runLocalFunctionHandlers
 export type { LocalFunctionHandler, LocalFunctionHandlers } from "./local-functions.js";
 export { localSkillFromDirectory, pendingLocalSkillCalls, runLocalSkillHandlers } from "./local-skills.js";
 export type { LocalSkillDirectoryOptions } from "./local-skills.js";
+export { AuthResource, DeviceAuthFlowError } from "./resources/auth.js";

package/dist/index.js

@@ -4,3 +4,4 @@ export { APIError, APIConnectionError, APIStatusError, AuthenticationError, BadR
 export * from "./types/index.js";
 export { functionCallOutputInput, pendingFunctionCalls, runLocalFunctionHandlers, } from "./local-functions.js";
 export { localSkillFromDirectory, pendingLocalSkillCalls, runLocalSkillHandlers } from "./local-skills.js";
+export { AuthResource, DeviceAuthFlowError } from "./resources/auth.js";

package/dist/resources/auth.d.ts

@@ -0,0 +1,14 @@
+import type { HTTPClient } from "../internal/http.js";
+import type { ApprovedDeviceAuth, DeviceAuthPollResult, DeviceAuthStart, PollDeviceAuthParams, StartDeviceAuthParams, WaitForDeviceAuthParams } from "../types/auth.js";
+import type { RequestOptions } from "../types/common.js";
+export declare class AuthResource {
+    private readonly http;
+    constructor(http: HTTPClient);
+    startDeviceAuth(params?: StartDeviceAuthParams, options?: RequestOptions): Promise<DeviceAuthStart>;
+    pollDeviceAuth(params: PollDeviceAuthParams, options?: RequestOptions): Promise<DeviceAuthPollResult>;
+    waitForDeviceAuth(params: WaitForDeviceAuthParams, options?: RequestOptions): Promise<ApprovedDeviceAuth>;
+}
+export declare class DeviceAuthFlowError extends Error {
+    readonly result?: DeviceAuthPollResult;
+    constructor(message: string, result?: DeviceAuthPollResult);
+}

package/dist/resources/auth.js

@@ -0,0 +1,87 @@
+const defaultDevicePollIntervalSeconds = 5;
+export class AuthResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    startDeviceAuth(params = {}, options = {}) {
+        return this.http.request("POST", "/v1/auth/device/start", params, options);
+    }
+    pollDeviceAuth(params, options = {}) {
+        requireDeviceCode(params.device_code);
+        return this.http.request("POST", "/v1/auth/device/poll", params, options);
+    }
+    async waitForDeviceAuth(params, options = {}) {
+        requireDeviceCode(params.device_code);
+        const startedAt = Date.now();
+        for (;;) {
+            throwIfAborted(params.signal);
+            const result = await this.pollDeviceAuth({ device_code: params.device_code }, options);
+            params.on_poll?.(result);
+            if (result.status === "approved" && result.access_token && result.refresh_token) {
+                return result;
+            }
+            if (result.status === "expired" || result.status === "consumed") {
+                throw new DeviceAuthFlowError(result.message || `Device auth ${result.status}`, result);
+            }
+            const timeoutMs = effectiveTimeoutMs(params, result);
+            if (timeoutMs !== undefined && Date.now() - startedAt >= timeoutMs) {
+                throw new DeviceAuthFlowError("Device auth timed out", result);
+            }
+            await sleep(pollDelayMs(params, result), params.signal);
+        }
+    }
+}
+export class DeviceAuthFlowError extends Error {
+    result;
+    constructor(message, result) {
+        super(message);
+        this.name = "DeviceAuthFlowError";
+        this.result = result;
+        Object.setPrototypeOf(this, DeviceAuthFlowError.prototype);
+    }
+}
+function requireDeviceCode(deviceCode) {
+    if (!deviceCode || !deviceCode.trim()) {
+        throw new TypeError("device_code is required");
+    }
+}
+function pollDelayMs(params, result) {
+    const seconds = params.interval_seconds ?? result.interval_seconds ?? defaultDevicePollIntervalSeconds;
+    return Math.max(1, seconds) * 1000;
+}
+function effectiveTimeoutMs(params, result) {
+    if (params.timeout_ms !== undefined) {
+        return Math.max(0, params.timeout_ms);
+    }
+    const expiresAt = result.expires_at;
+    if (!expiresAt)
+        return undefined;
+    return Math.max(0, expiresAt * 1000 - Date.now());
+}
+function sleep(ms, signal) {
+    if (!signal) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    throwIfAborted(signal);
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(cleanupResolve, ms);
+        signal.addEventListener("abort", cleanupReject, { once: true });
+        function cleanupResolve() {
+            signal?.removeEventListener("abort", cleanupReject);
+            resolve();
+        }
+        function cleanupReject() {
+            clearTimeout(timeout);
+            reject(abortError());
+        }
+    });
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw abortError();
+    }
+}
+function abortError() {
+    return new DOMException("Device auth wait aborted", "AbortError");
+}

package/dist/types/auth.d.ts

@@ -0,0 +1,63 @@
+export type DeviceAuthStatus = "pending" | "approved" | "expired" | "consumed" | string;
+export interface DeviceAuthStart {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_at: number;
+    interval_seconds: number;
+}
+export interface AuthSession {
+    access_token: string;
+    refresh_token: string;
+    token_type?: string;
+    access_token_expires_at: number;
+    refresh_token_expires_at?: number;
+    user_id: string;
+    workspace_id: string;
+    workspace_name?: string;
+    workspace_role: string;
+    scopes: string[];
+}
+export interface DeviceAuthPollResult {
+    status: DeviceAuthStatus;
+    message?: string;
+    interval_seconds?: number;
+    expires_at?: number;
+    access_token?: string;
+    refresh_token?: string;
+    token_type?: string;
+    access_token_expires_at?: number;
+    refresh_token_expires_at?: number;
+    user_id?: string;
+    workspace_id?: string;
+    workspace_name?: string;
+    workspace_role?: string;
+    scopes?: string[];
+}
+export type ApprovedDeviceAuth = DeviceAuthPollResult & {
+    status: "approved";
+    access_token: string;
+    refresh_token: string;
+    access_token_expires_at: number;
+    user_id: string;
+    workspace_id: string;
+    workspace_role: string;
+    scopes: string[];
+};
+export interface StartDeviceAuthParams {
+    client_name?: string;
+}
+export interface PollDeviceAuthParams {
+    device_code: string;
+}
+export interface WaitForDeviceAuthParams extends PollDeviceAuthParams {
+    /** Polling interval in seconds. Defaults to the server interval or 5 seconds. */
+    interval_seconds?: number;
+    /** Overall wait timeout in milliseconds. Defaults to the challenge expiry when present. */
+    timeout_ms?: number;
+    /** Optional cancellation signal for CLI/Desktop integrations. */
+    signal?: AbortSignal;
+    /** Called after every poll response, including pending responses. */
+    on_poll?: (result: DeviceAuthPollResult) => void;
+}

package/dist/types/auth.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -6,3 +6,4 @@ export * from "./streaming.js";
 export * from "./catalog.js";
 export * from "./volumes.js";
 export * from "./skills.js";
+export * from "./auth.js";

package/dist/types/index.js

@@ -6,3 +6,4 @@ export * from "./streaming.js";
 export * from "./catalog.js";
 export * from "./volumes.js";
 export * from "./skills.js";
+export * from "./auth.js";

package/dist/types/responses.d.ts

@@ -2,10 +2,17 @@ import type { AgentCapabilityPreference, ErrorInfo, ModelRoutingMode, ModelRouti
 import type { ContentPart, Input, MemoryOptions, ReasoningConfig, ResponseFormat } from "./input.js";
 import type { LocalSkillDescriptor, SkillReference } from "./skills.js";
 import type { Tool } from "./tools.js";
+export interface CallerContext {
+    timezone?: string;
+    locale?: string;
+    locality?: string;
+    extra?: unknown;
+}
 export interface ResponseCreateParamsBase {
     input: Input;
     instructions?: string;
     language_preference?: string;
+    caller_context?: CallerContext;
     model?: string;
     models?: string[];
     model_routing?: ModelRoutingMode;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.1.0";
-export declare const USER_AGENT = "@agent-api/sdk/1.1.0";
+export declare const VERSION = "1.1.1";
+export declare const USER_AGENT = "@agent-api/sdk/1.1.1";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "1.1.0";
+export const VERSION = "1.1.1";
 export const USER_AGENT = `@agent-api/sdk/${VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-api/sdk",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Production JavaScript SDK for the Managed Agent API",
   "license": "MIT",
   "repository": {