@near-intents-agent-api/sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,613 @@
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
+import { base64urlnopad } from "@scure/base";
+//#region src/errors.ts
+/** A transport, cancellation or parsing failure carrying the key of the original request. */
+var AgentApiRequestError = class extends Error {
+	idempotencyKey;
+	constructor(cause, idempotencyKey) {
+		super(cause instanceof Error ? cause.message : String(cause), { cause });
+		this.name = cause instanceof Error ? cause.name : "AgentApiRequestError";
+		this.idempotencyKey = idempotencyKey;
+	}
+};
+/** Preserve SDK error classes and unkeyed failures; wrap other keyed failures for safe retry. */
+function requestError(error, idempotencyKey) {
+	if (idempotencyKey === void 0 || error instanceof AgentApiError || error instanceof AgentApiResponseTooLargeError) return error;
+	return new AgentApiRequestError(error, idempotencyKey);
+}
+/** A success or error body exceeded the client's byte budget before JSON parsing. */
+var AgentApiResponseTooLargeError = class extends Error {
+	code = "response_too_large";
+	status;
+	maxResponseBytes;
+	idempotencyKey;
+	constructor(status, maxResponseBytes, idempotencyKey) {
+		super(`Response exceeds ${maxResponseBytes} bytes`);
+		this.name = "AgentApiResponseTooLargeError";
+		this.status = status;
+		this.maxResponseBytes = maxResponseBytes;
+		this.idempotencyKey = idempotencyKey;
+	}
+};
+/**
+* A non-2xx response. `code` is the first error's stable snake_case code; branch on it, never on
+* `title` or `detail`. `errors` holds every entry (validation failures return one per field).
+*/
+var AgentApiError = class extends Error {
+	status;
+	code;
+	title;
+	detail;
+	retryable;
+	availableAt;
+	requestId;
+	errors;
+	idempotencyKey;
+	constructor(status, document, idempotencyKey) {
+		const first = document?.errors?.[0];
+		super(first?.detail ?? first?.title ?? `HTTP ${status}`);
+		this.name = "AgentApiError";
+		this.status = status;
+		this.code = first?.code ?? "http_error";
+		this.title = first?.title ?? `HTTP ${status}`;
+		this.detail = first?.detail;
+		this.retryable = first?.meta?.retryable ?? false;
+		this.availableAt = first?.meta?.available_at;
+		this.requestId = document?.meta?.request_id;
+		this.errors = document?.errors ?? [];
+		this.idempotencyKey = idempotencyKey;
+	}
+};
+//#endregion
+//#region src/generated/routes.ts
+const endpoints = {
+	generateIntent: {
+		operationId: "generateIntent",
+		method: "post",
+		path: "/v1/generate-intent",
+		idempotency: "optional"
+	},
+	submitIntent: {
+		operationId: "submitIntent",
+		method: "post",
+		path: "/v1/submit-intent"
+	},
+	getStatus: {
+		operationId: "getStatus",
+		method: "get",
+		path: "/v1/status"
+	},
+	getHistory: {
+		operationId: "getHistory",
+		method: "get",
+		path: "/v1/agents/{agent_id}/history"
+	},
+	listAgents: {
+		operationId: "listAgents",
+		method: "get",
+		path: "/v1/agents"
+	},
+	getAgent: {
+		operationId: "getAgent",
+		method: "get",
+		path: "/v1/agents/{agent_id}"
+	},
+	getWallet: {
+		operationId: "getWallet",
+		method: "get",
+		path: "/v1/agents/{agent_id}/wallet"
+	},
+	getBalances: {
+		operationId: "getBalances",
+		method: "get",
+		path: "/v1/agents/{agent_id}/balances"
+	},
+	getPolicy: {
+		operationId: "getPolicy",
+		method: "get",
+		path: "/v1/agents/{agent_id}/policy"
+	},
+	getPolicyHistory: {
+		operationId: "getPolicyHistory",
+		method: "get",
+		path: "/v1/agents/{agent_id}/policy/history"
+	},
+	listGrants: {
+		operationId: "listGrants",
+		method: "get",
+		path: "/v1/agents/{agent_id}/grants"
+	},
+	listScheduledExecutions: {
+		operationId: "listScheduledExecutions",
+		method: "get",
+		path: "/v1/agents/{agent_id}/executions/scheduled"
+	},
+	getContainment: {
+		operationId: "getContainment",
+		method: "get",
+		path: "/v1/agents/{agent_id}/containment"
+	},
+	listApprovals: {
+		operationId: "listApprovals",
+		method: "get",
+		path: "/v1/agents/{agent_id}/approvals"
+	},
+	getApproval: {
+		operationId: "getApproval",
+		method: "get",
+		path: "/v1/agents/{agent_id}/approvals/{approval_id}"
+	},
+	getAddress: {
+		operationId: "getAddress",
+		method: "get",
+		path: "/v1/agents/{agent_id}/addresses/{chain}"
+	},
+	listProviderRecords: {
+		operationId: "listProviderRecords",
+		method: "get",
+		path: "/v1/agents/{agent_id}/provider/{kind}"
+	},
+	swap: {
+		operationId: "swap",
+		method: "post",
+		path: "/v1/agents/{agent_id}/swap",
+		grant: true,
+		idempotency: "required"
+	},
+	withdraw: {
+		operationId: "withdraw",
+		method: "post",
+		path: "/v1/agents/{agent_id}/withdraw",
+		grant: true,
+		idempotency: "required"
+	},
+	transfer: {
+		operationId: "transfer",
+		method: "post",
+		path: "/v1/agents/{agent_id}/transfer",
+		grant: true,
+		idempotency: "required"
+	},
+	shield: {
+		operationId: "shield",
+		method: "post",
+		path: "/v1/agents/{agent_id}/shield",
+		grant: true,
+		idempotency: "required"
+	},
+	unshield: {
+		operationId: "unshield",
+		method: "post",
+		path: "/v1/agents/{agent_id}/unshield",
+		grant: true,
+		idempotency: "required"
+	},
+	deposit: {
+		operationId: "deposit",
+		method: "post",
+		path: "/v1/agents/{agent_id}/deposit",
+		idempotency: "required"
+	},
+	recover: {
+		operationId: "recover",
+		method: "post",
+		path: "/v1/agents/{agent_id}/recover",
+		grant: true,
+		idempotency: "required"
+	},
+	signMessage: {
+		operationId: "signMessage",
+		method: "post",
+		path: "/v1/agents/{agent_id}/sign-message",
+		grant: true
+	},
+	getTokens: {
+		operationId: "getTokens",
+		method: "get",
+		path: "/v1/tokens"
+	},
+	getNetwork: {
+		operationId: "getNetwork",
+		method: "get",
+		path: "/v1/network"
+	},
+	whoami: {
+		operationId: "whoami",
+		method: "get",
+		path: "/v1/whoami"
+	},
+	getPartnerQuota: {
+		operationId: "getPartnerQuota",
+		method: "get",
+		path: "/v1/quotas"
+	}
+};
+//#endregion
+//#region src/grants.ts
+/** Shape of a grant token: `ngt_` plus 32 random bytes in unpadded base64url. */
+const grantTokenPattern = /^ngt_[A-Za-z0-9_-]{43}$/;
+/** The commitment of an existing grant token. */
+function grantCommitment(token) {
+	return bytesToHex(sha256(utf8ToBytes(token)));
+}
+/**
+* Creates the token for one new grant. Send only `commitment` in `grant_issue`; the owner signs
+* it, and afterwards `api.forGrant(token)` runs calls under that grant. Use a new token for every
+* grant.
+*/
+function createGrantCredential() {
+	const token = `ngt_${base64urlnopad.encode(crypto.getRandomValues(new Uint8Array(32)))}`;
+	return {
+		token,
+		commitment: grantCommitment(token)
+	};
+}
+//#endregion
+//#region src/idempotency.ts
+/** Creates a key for one logical request. Save it before sending when recovery must survive a restart. */
+function createIdempotencyKey() {
+	return crypto.randomUUID();
+}
+/** Resolve one request's identity before dispatch; recovery must use its existing key. */
+function requestIdempotency(endpoint, call) {
+	const dry = (endpoint === endpoints.swap || endpoint === endpoints.withdraw) && call.body?.dry === true;
+	const keyed = Boolean(endpoint.idempotency) && !dry;
+	return {
+		dry,
+		keyed,
+		idempotencyKey: keyed && endpoint !== endpoints.recover && call.idempotencyKey === void 0 ? createIdempotencyKey() : call.idempotencyKey
+	};
+}
+//#endregion
+//#region src/response-utils.ts
+/** Parse a bounded response, preserving HTTP errors even when their body is not JSON. */
+async function readResponseJson(response, maxResponseBytes, idempotencyKey) {
+	const text = await readResponseText(response, maxResponseBytes, idempotencyKey);
+	let json;
+	try {
+		json = text ? JSON.parse(text) : void 0;
+	} catch (error) {
+		if (response.ok) throw error;
+	}
+	if (!response.ok) throw new AgentApiError(response.status, json, idempotencyKey);
+	return json;
+}
+/** Count bytes before retaining chunks; decode once to preserve Fetch's UTF-8 behavior. */
+async function readResponseText(response, maxResponseBytes, idempotencyKey) {
+	const reader = response.body?.getReader();
+	if (!reader) return "";
+	const chunks = [];
+	let size = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			size += value.byteLength;
+			if (size > maxResponseBytes) throw new AgentApiResponseTooLargeError(response.status, maxResponseBytes, idempotencyKey);
+			chunks.push(value);
+		}
+		return new TextDecoder().decode(Buffer.concat(chunks, size));
+	} finally {
+		reader.cancel().catch(() => void 0);
+		reader.releaseLock();
+	}
+}
+//#endregion
+//#region src/client.ts
+/** The hosted API. Pass `baseUrl` only for a self-hosted or local deployment. */
+const DEFAULT_BASE_URL = "https://api.agentsonintents.com";
+const settlementEndpoints = new Set([
+	endpoints.swap,
+	endpoints.withdraw,
+	endpoints.transfer,
+	endpoints.shield,
+	endpoints.unshield
+]);
+/** `{agent_id}` path segments filled from `params`, each URI-encoded. */
+function fillPath(template, params = {}) {
+	return template.replace(/\{([^}]+)\}/g, (_, name) => {
+		const value = params[name];
+		if (value === void 0) throw new Error(`missing path parameter ${name}`);
+		return encodeURIComponent(value);
+	});
+}
+/**
+* Typed client for the NEAR Intents Agent API. One method per endpoint; paths and methods come
+* from the shared endpoint registry, so the client cannot drift from the server.
+*
+* Owner actions follow a generate/submit shape: `generateIntent` returns
+* `intent: { standard, payload }`, your frontend has the owner's wallet sign `payload`
+* unchanged, and `submitIntent` sends the wallet's output back. `getStatus` tracks the result.
+*/
+var AgentApi = class AgentApi {
+	origin;
+	fetcher;
+	maxResponseBytes;
+	constructor(options) {
+		this.options = options;
+		const url = new URL(options.baseUrl ?? "https://api.agentsonintents.com");
+		const local = [
+			"localhost",
+			"127.0.0.1",
+			"[::1]"
+		].includes(url.hostname);
+		if (url.protocol !== "https:" && !(url.protocol === "http:" && local)) throw new Error("baseUrl must use HTTPS");
+		if (url.username || url.password || url.search || url.hash || url.pathname !== "/") throw new Error("baseUrl must be a plain origin");
+		if (!/^naa_[A-Za-z0-9_-]{43}$/.test(options.apiKey)) throw new Error("apiKey is not a naa_ key");
+		if (options.grantToken !== void 0 && !grantTokenPattern.test(options.grantToken)) throw new Error("grantToken is not an ngt_ token");
+		const maxResponseBytes = options.maxResponseBytes === void 0 ? 8 * 1048576 : options.maxResponseBytes;
+		if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes <= 0) throw new RangeError("maxResponseBytes must be a positive safe integer");
+		this.origin = url.href.replace(/\/$/, "");
+		this.fetcher = options.fetch ?? fetch;
+		this.maxResponseBytes = maxResponseBytes;
+	}
+	getPartnerQuota(options = {}) {
+		return this.call(endpoints.getPartnerQuota, options);
+	}
+	headers(endpoint, call) {
+		const headers = {
+			accept: "application/json",
+			"x-api-key": this.options.apiKey
+		};
+		if (call.body !== void 0) headers["content-type"] = "application/json";
+		if (call.idempotencyKey !== void 0) headers["idempotency-key"] = call.idempotencyKey;
+		if (endpoint.grant && this.options.grantToken) headers["x-grant-token"] = this.options.grantToken;
+		return headers;
+	}
+	async call(endpoint, call = {}) {
+		const { dry, keyed, idempotencyKey } = requestIdempotency(endpoint, call);
+		try {
+			const url = new URL(`${this.origin}${fillPath(endpoint.path, call.params)}`);
+			for (const [key, value] of Object.entries(call.query ?? {})) if (value !== void 0) url.searchParams.set(key, String(value));
+			const headers = this.headers(endpoint, {
+				...call,
+				idempotencyKey
+			});
+			const settlement = settlementEndpoints.has(endpoint) && !dry;
+			const signals = [AbortSignal.timeout(this.options.timeoutMs ?? (settlement ? 15e4 : 65e3))];
+			if (call.signal) signals.push(call.signal);
+			const json = await readResponseJson(await this.fetcher(url, {
+				method: endpoint.method.toUpperCase(),
+				headers,
+				body: call.body === void 0 ? void 0 : JSON.stringify(call.body),
+				signal: AbortSignal.any(signals),
+				redirect: "error",
+				credentials: "omit"
+			}), this.maxResponseBytes, idempotencyKey);
+			return keyed && idempotencyKey !== void 0 ? {
+				...json,
+				idempotencyKey
+			} : json;
+		} catch (error) {
+			throw requestError(error, idempotencyKey);
+		}
+	}
+	/**
+	* A client that runs delegated calls under one owner grant. Keep one per session, assistant or
+	* bot: each carries its own token, so concurrent calls never borrow another grant.
+	*/
+	forGrant(grantToken) {
+		return new AgentApi({
+			...this.options,
+			grantToken,
+			maxResponseBytes: this.maxResponseBytes
+		});
+	}
+	/**
+	* Builds the payload the owner's wallet must sign for one owner action. Omission generates
+	* a new `idempotencyKey`; reuse the response/error key to retry the same intent.
+	* Interrupted generation returns
+	* `intent_generation_recovery_required` unless a saved payload or complete preparation can
+	* recover the original request; the key never
+	* starts another builder. Keep that key for recovery.
+	*/
+	generateIntent(request, options = {}) {
+		return this.call(endpoints.generateIntent, {
+			body: request,
+			...options
+		});
+	}
+	/** Sends the wallet's output for a generated intent. Resubmitting the same signature is safe. */
+	submitIntent(request, options = {}) {
+		return this.call(endpoints.submitIntent, {
+			body: request,
+			...options
+		});
+	}
+	/**
+	* Status of an intent or execution. `waitMs` (≤ 30 000) long-polls until the status is
+	* terminal, needs a signature, or the wait ends.
+	*/
+	getStatus(correlationId, options = {}) {
+		return this.call(endpoints.getStatus, {
+			query: {
+				correlation_id: correlationId,
+				wait_ms: options.waitMs,
+				refresh: options.refresh
+			},
+			signal: options.signal
+		});
+	}
+	/** An agent's intents and executions, newest first. */
+	getHistory(agentId, query = {}, options = {}) {
+		return this.call(endpoints.getHistory, {
+			params: { agent_id: agentId },
+			query,
+			...options
+		});
+	}
+	listAgents(query = {}, options = {}) {
+		return this.call(endpoints.listAgents, {
+			query,
+			...options
+		});
+	}
+	getAgent(agentId, options = {}) {
+		return this.call(endpoints.getAgent, {
+			params: { agent_id: agentId },
+			...options
+		});
+	}
+	getWallet(agentId, options = {}) {
+		return this.call(endpoints.getWallet, {
+			params: { agent_id: agentId },
+			...options
+		});
+	}
+	getBalances(agentId, query = {}, options = {}) {
+		return this.call(endpoints.getBalances, {
+			params: { agent_id: agentId },
+			query,
+			...options
+		});
+	}
+	/** Public: every asset agents can use, with chain and USD price. Needs no API key. */
+	async getTokens(options = {}) {
+		return (await this.call(endpoints.getTokens, options)).data;
+	}
+	getPolicy(agentId, options = {}) {
+		return this.call(endpoints.getPolicy, {
+			params: { agent_id: agentId },
+			...options
+		});
+	}
+	getPolicyHistory(agentId, query = {}, options = {}) {
+		return this.call(endpoints.getPolicyHistory, {
+			params: { agent_id: agentId },
+			query,
+			...options
+		});
+	}
+	async listGrants(agentId, options = {}) {
+		return (await this.call(endpoints.listGrants, {
+			params: { agent_id: agentId },
+			...options
+		})).data;
+	}
+	/** Executions the timelock holds, earliest release first; follow `next_cursor` for more. */
+	listScheduledExecutions(agentId, query = {}, options = {}) {
+		return this.call(endpoints.listScheduledExecutions, {
+			params: { agent_id: agentId },
+			query,
+			...options
+		});
+	}
+	getContainment(agentId, query = {}, options = {}) {
+		return this.call(endpoints.getContainment, {
+			params: { agent_id: agentId },
+			query,
+			...options
+		});
+	}
+	async listApprovals(agentId, options = {}) {
+		return (await this.call(endpoints.listApprovals, {
+			params: { agent_id: agentId },
+			...options
+		})).data;
+	}
+	getApproval(agentId, approvalId, options = {}) {
+		return this.call(endpoints.getApproval, {
+			params: {
+				agent_id: agentId,
+				approval_id: approvalId
+			},
+			...options
+		});
+	}
+	getAddress(agentId, chain, options = {}) {
+		return this.call(endpoints.getAddress, {
+			params: {
+				agent_id: agentId,
+				chain
+			},
+			...options
+		});
+	}
+	listProviderRecords(agentId, kind, query = {}, options = {}) {
+		return this.call(endpoints.listProviderRecords, {
+			params: {
+				agent_id: agentId,
+				kind
+			},
+			query,
+			...options
+		});
+	}
+	swap(agentId, request, options = {}) {
+		return this.call(endpoints.swap, {
+			params: { agent_id: agentId },
+			body: request,
+			...options
+		});
+	}
+	withdraw(agentId, request, options = {}) {
+		return this.call(endpoints.withdraw, {
+			params: { agent_id: agentId },
+			body: request,
+			...options
+		});
+	}
+	transfer(agentId, request, options = {}) {
+		return this.call(endpoints.transfer, {
+			params: { agent_id: agentId },
+			body: request,
+			...options
+		});
+	}
+	shield(agentId, request, options = {}) {
+		return this.call(endpoints.shield, {
+			params: { agent_id: agentId },
+			body: request,
+			...options
+		});
+	}
+	unshield(agentId, request, options = {}) {
+		return this.call(endpoints.unshield, {
+			params: { agent_id: agentId },
+			body: request,
+			...options
+		});
+	}
+	/** Creates an inbound public or confidential deposit address; no grant token is needed. */
+	deposit(agentId, request, options = {}) {
+		return this.call(endpoints.deposit, {
+			params: { agent_id: agentId },
+			body: request,
+			...options
+		});
+	}
+	/** First dispatch of an UNCERTAIN execution that provably never reached the provider. Requires its original key. */
+	recover(agentId, request, options) {
+		return this.call(endpoints.recover, {
+			params: { agent_id: agentId },
+			body: request,
+			...options
+		});
+	}
+	/**
+	* Signs a canonical identity challenge with the agent's NEAR key (NEP-413). Needs a grant token,
+	* a policy listing the recipient, and a server with NEAR message signing enabled.
+	*/
+	signMessage(agentId, request, options = {}) {
+		return this.call(endpoints.signMessage, {
+			params: { agent_id: agentId },
+			body: request,
+			...options
+		});
+	}
+	getNetwork(options = {}) {
+		return this.call(endpoints.getNetwork, options);
+	}
+	whoami(options = {}) {
+		return this.call(endpoints.whoami, options);
+	}
+};
+/** Creates a client. Keep the API key on your backend. */
+function createAgentApi(options) {
+	return new AgentApi(options);
+}
+//#endregion
+export { AgentApi, AgentApiError, AgentApiRequestError, AgentApiResponseTooLargeError, DEFAULT_BASE_URL, createAgentApi, createGrantCredential, createIdempotencyKey, grantCommitment };
+
+//# sourceMappingURL=index.mjs.map