@aexhq/sdk 0.68.0 → 0.70.0

package/README.md

@@ -1,35 +1,44 @@
-# @aexhq/sdk
+# Aex SDK
 
-The hosted Aex client uses the neutral Brain composition API with the `https://api.aex.dev` base
-URL and an Aex API key.
+Install `@aexhq/sdk`. Create an API key at https://aex.dev/dashboard.
 
 ```ts
-import { Aex, brainEnv } from "@aexhq/sdk";
-import { awsMicroVm } from "@aexhq/env-aws-microvm";
-import { pi } from "@aexhq/agentloop-pi";
-import { bash, read } from "@aexhq/tools";
+import { Aex, agentloop, brainEnv, component, hostEnv, tool } from "@aexhq/sdk";
 
 const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-const workspace = awsMicroVm({ name: "sandbox", url: process.env.ENVIRONMENT_URL, token: process.env.ENVIRONMENT_TOKEN, region: "eu-west-2" });
-const session = await aex.sessions.create({
-  model: {
-    provider: "vercel-ai-gateway",
-    name: "openai/gpt-5-mini",
-    apiKey: process.env.VERCEL_AI_GATEWAY_API_KEY!,
-  },
-  agentloop: pi({ env: brainEnv({ name: "brain" }) }),
-  tools: [read({ env: workspace }), bash({ env: workspace })],
-});
-
-await session.send("Inspect the workspace.");
-for await (const event of session.events()) console.log(event);
+console.log(await aex.account.get());
 ```
 
-Aex supplies hosted authentication and policy. Brain admission, Tool placement, Environment
-operations, operation keys, and event cursors are handled by the shared Brain SDK.
+`Aex` extends the pinned Brain client. Its sessions, registration, Events, Components and
+extension builders are Brain's implementations. Existing Brain extension packages work with
+the same contracts. See https://aex.dev/docs for a complete session example.
 
-This example requires a separately deployed AWS Environment driver. Supply its URL and bearer
-credential as `ENVIRONMENT_URL` and `ENVIRONMENT_TOKEN`; the SDK keeps the credential out of the
-Environment configuration and Tool implementation descriptors. See the
-[Environment package](https://github.com/aexhq/extensions/tree/main/packages/env-aws-microvm)
-for its supported runtime and deployment boundary.
+Place uploaded Wasm Agentloops and Tools in `brainEnv` for hosted execution. `hostEnv`
+executes application functions in your process. Native hosted Components receive no server
+secrets, filesystem or network grants. Customer-selected HTTP Environments are not enabled
+on the initial deployment. Supply your model key per session.
+
+`account.get()` and `account.usage()` accept a workload API key. `keys` management requires
+an authenticated account session and is normally performed in the dashboard. API keys do
+not grant authority to create more credentials. New key secrets are returned once.
+
+## Account management
+
+Use an account session obtained through browser login for account management. Workload
+API keys remain scoped to runtime operations and read-only account/usage access.
+
+```ts
+const account = new Aex({ accountToken: process.env.AEX_ACCOUNT_TOKEN! });
+await account.keys.list();
+const issued = await account.keys.create({ name: "My app" });
+await account.keys.update(issued.key.id, { name: "Renamed app" });
+await account.keys.delete(issued.key.id);
+await account.account.get(); // includes billing status and limits
+await account.account.usage();
+await account.account.logout();
+```
+
+`account.account.authorizeLogin({code_challenge, redirect_uri})` and
+`Aex.exchangeLogin({code, code_verifier, redirect_uri})` expose the shared HTTP login
+contract for clients. The `@aexhq/cli` package handles opening the browser, PKCE,
+loopback callback and local credential storage.

package/dist/generated.d.ts

@@ -0,0 +1,113 @@
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "Billing".
+ */
+export type Billing = "preview_customer_model_keys";
+export interface AexContracts {
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "Limits".
+ */
+export interface Limits {
+    accounts: number;
+    active_turns_per_account: number;
+    artifact_bytes_per_account: number;
+    artifacts_per_account: number;
+    claims_per_account: number;
+    hosts_per_account: number;
+    keys_per_account: number;
+    minimum_free_disk_bytes: number;
+    request_bytes: number;
+    requests: number;
+    requests_per_account: number;
+    response_bytes: number;
+    retained_bytes_per_account: number;
+    retention_secs: number;
+    sessions_per_account: number;
+    streams_per_account: number;
+    turn_reserve_bytes: number;
+    upstream_timeout_secs: number;
+    usage_max_age_secs: number;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "Usage".
+ */
+export interface Usage {
+    active_turns: number;
+    measured_at?: number | null;
+    retained_bytes: number;
+    sessions: number;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "Account".
+ */
+export interface Account {
+    billing: Billing;
+    created: number;
+    email?: string | null;
+    id: string;
+    limits: Limits;
+    usage: Usage;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "ApiKey".
+ */
+export interface ApiKey {
+    active: boolean;
+    created: number;
+    id: string;
+    name: string;
+    prefix: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "IssuedKey".
+ */
+export interface IssuedKey {
+    key: ApiKey;
+    token: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "KeyInput".
+ */
+export interface KeyInput {
+    name: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "LoginGrantInput".
+ */
+export interface LoginGrantInput {
+    code_challenge: string;
+    redirect_uri: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "LoginGrant".
+ */
+export interface LoginGrant {
+    code: string;
+    expires: number;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "LoginExchange".
+ */
+export interface LoginExchange {
+    code: string;
+    code_verifier: string;
+    redirect_uri: string;
+}
+/**
+ * This interface was referenced by `AexContracts`'s JSON-Schema
+ * via the `definition` "AccountSession".
+ */
+export interface AccountSession {
+    expires: number;
+    token: string;
+}

package/dist/generated.js

@@ -0,0 +1,2 @@
+/* Generated from aex-server schemas. */
+export {};

package/dist/index.d.ts

@@ -1,13 +1,31 @@
+export * from "@aexhq/brain";
+export type * from "./generated.js";
 import { Brain, type BrainOptions } from "@aexhq/brain";
-export { BrainError as AexError } from "@aexhq/brain";
-export { agentloop, brainEnv, component, environment, hostEnv, tool } from "@aexhq/brain";
-export type { PlacedAgentloop, BrainEnvOptions, Component, CreateSessionOptions, CustomProviderModel, Environment, KnownProviderId, KnownProviderModel, ModelContentBlock, ModelMessage, ModelResponse, ModelSelection, ModelStopReason, ModelUsage, OperationOptions, Outcome, Schema, SchemaInput, SchemaOutput, SessionEvent, SessionState, SessionStreamEvent, SessionTool, PlacedTool, ToolDefinition, VercelAiGatewayModel, } from "@aexhq/brain";
-export interface AexOptions {
-    apiKey: string;
+import type { Account, Usage, ApiKey, IssuedKey, KeyInput, LoginGrantInput, LoginGrant, LoginExchange, AccountSession } from "./generated.js";
+export type AexConnection = Omit<BrainOptions, "token" | "baseUrl"> & {
     baseUrl?: string;
-    fetch?: BrainOptions["fetch"];
-    timeoutMs?: number;
-}
+};
+export type AexOptions = AexConnection & ({
+    apiKey: string;
+    accountToken?: never;
+} | {
+    accountToken: string;
+    apiKey?: never;
+});
 export declare class Aex extends Brain {
-    constructor(options: AexOptions);
+    constructor({ apiKey, accountToken, ...options }: AexOptions);
+    static exchangeLogin(input: LoginExchange, options?: AexConnection): Promise<AccountSession>;
+    readonly account: {
+        get: () => Promise<Account>;
+        usage: () => Promise<Usage>;
+        logout: () => Promise<void>;
+        authorizeLogin: (input: LoginGrantInput) => Promise<LoginGrant>;
+    };
+    /** Key management requires an account session; workload API keys cannot create credentials. */
+    readonly keys: {
+        list: () => Promise<ApiKey[]>;
+        create: (input: KeyInput) => Promise<IssuedKey>;
+        update: (id: string, input: KeyInput) => Promise<ApiKey>;
+        delete: (id: string) => Promise<void>;
+    };
 }

package/dist/index.js

@@ -1,16 +1,25 @@
+export * from "@aexhq/brain";
 import { Brain } from "@aexhq/brain";
-export { BrainError as AexError } from "@aexhq/brain";
-export { agentloop, brainEnv, component, environment, hostEnv, tool } from "@aexhq/brain";
-const DEFAULT_API_URL = "https://api.aex.dev";
 export class Aex extends Brain {
-    constructor(options) {
-        if (options.apiKey.trim() === "")
-            throw new TypeError("Aex apiKey cannot be empty");
-        super({
-            baseUrl: options.baseUrl ?? DEFAULT_API_URL,
-            token: options.apiKey,
-            ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
-            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
-        });
+    constructor({ apiKey, accountToken, ...options }) {
+        if (!(apiKey || accountToken) || (apiKey && accountToken))
+            throw new TypeError("one apiKey or accountToken is required");
+        super({ baseUrl: "https://api.aex.dev", ...options, token: apiKey ?? accountToken });
     }
+    static exchangeLogin(input, options = {}) {
+        return new Brain({ baseUrl: "https://api.aex.dev", ...options }).request("POST", "/v1/auth/exchange", input);
+    }
+    account = {
+        get: () => this.request("GET", "/v1/account"),
+        usage: () => this.request("GET", "/v1/usage"),
+        logout: () => this.request("DELETE", "/v1/account/session"),
+        authorizeLogin: (input) => this.request("POST", "/v1/auth/grants", input),
+    };
+    /** Key management requires an account session; workload API keys cannot create credentials. */
+    keys = {
+        list: () => this.request("GET", "/v1/keys"),
+        create: (input) => this.request("POST", "/v1/keys", input),
+        update: (id, input) => this.request("PATCH", `/v1/keys/${encodeURIComponent(id)}`, input),
+        delete: (id) => this.request("DELETE", `/v1/keys/${encodeURIComponent(id)}`),
+    };
 }

package/package.json

@@ -1,42 +1,39 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.68.0",
-  "description": "TypeScript SDK for Aex sessions",
-  "license": "Apache-2.0",
-  "homepage": "https://aex.dev",
+  "version": "0.70.0",
+  "description": "Aex accounts and hosted sessions using the Brain SDK",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aexhq/aex.git",
     "directory": "packages/sdk"
   },
-  "type": "module",
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "publishConfig": {
-    "access": "public",
-    "provenance": false,
-    "tag": "next"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
+    }
   },
   "files": [
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "tsc -p tsconfig.json && node --test"
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
   },
   "dependencies": {
-    "@aexhq/brain": "0.18.0"
+    "@aexhq/brain": "0.19.0"
   },
-  "devDependencies": {
-    "typescript": "5.9.3"
+  "scripts": {
+    "gen": "node ../../tools/sdk-contracts.mjs",
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build"
   }
 }