@agentforge-io/sdk-console 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# @agentforge-io/sdk-console
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Session client for **admin apps** of the AgentForge platform: the Poodleck Console
+(Expo: iOS, Android, web), or any client that signs in as an AgentForge **user**
+(dashboard JWT) rather than as an App (`@agentforge-io/sdk-server`, `sk_live_`).
+
+- Injectable `fetch`: runs in React Native, browsers and Node. No Node-only APIs in
+  the runtime code (no Buffer / crypto / fs).
+- `TokenStore` adapter: you decide where the tokens live (SecureStore, web storage, memory).
+- Automatic **single-flight refresh** on 401, then one retry. A burst of parallel 401s
+  triggers exactly one `POST /auth/refresh` (the refresh token rotates on use).
+- Typed `ApiError` (`status`, `code`, `message`, `details`) and an `onSignedOut` callback.
+- `forTenant(tenantId)` binds every `admin/tenants/:tenantId/...` resource to a workspace.
+
+## Usage (Expo / React Native)
+
+```ts
+import * as SecureStore from 'expo-secure-store';
+import { ConsoleClient, ApiError, type TokenStore } from '@agentforge-io/sdk-console';
+
+const ACCESS = 'af.access';
+const REFRESH = 'af.refresh';
+
+const tokenStore: TokenStore = {
+  getAccessToken: () => SecureStore.getItemAsync(ACCESS),
+  getRefreshToken: () => SecureStore.getItemAsync(REFRESH),
+  setTokens: async ({ accessToken, refreshToken }) => {
+    await SecureStore.setItemAsync(ACCESS, accessToken);
+    await SecureStore.setItemAsync(REFRESH, refreshToken);
+  },
+  clear: async () => {
+    await SecureStore.deleteItemAsync(ACCESS);
+    await SecureStore.deleteItemAsync(REFRESH);
+  },
+};
+
+export const af = new ConsoleClient({
+  baseURL: process.env.EXPO_PUBLIC_AGENTFORGE_URL!,
+  tokenStore,
+  // Refresh was rejected or there is no refresh token: the store is already
+  // cleared, send the user to sign-in. Not fired by an explicit auth.logout().
+  onSignedOut: () => router.replace('/welcome'),
+});
+
+// Sign in (stores the tokens through the TokenStore)
+await af.auth.login({ email, password });
+
+// Workspaces the user can access, with their role in each
+const { items } = await af.tenants.listMine();
+
+// Everything workspace-scoped hangs off forTenant()
+const ws = af.forTenant(items[0].id);
+const { items: teams } = await ws.teams.list();
+const { groups } = await ws.tools.grouped({ q: 'mail' });
+const { items: gallery } = await ws.templates.list({ kind: 'team' });
+await ws.templates.install(gallery[0].id, { name: 'Mi tienda' });
+
+try {
+  await ws.teams.publish(teamId);
+} catch (e) {
+  if (e instanceof ApiError && e.code === 'team_not_publishable') {
+    console.log((e.details as { issues: unknown[] }).issues);
+  }
+}
+```
+
+On web, `MemoryTokenStore` (exported) or a `localStorage`-backed store works the same way.
+
+## Options
+
+| Option | Notes |
+|---|---|
+| `baseURL` | Platform URL. A trailing slash is stripped. |
+| `tokenStore` | `getAccessToken / getRefreshToken / setTokens / clear`, each sync or async. |
+| `fetch` | Defaults to the global one. |
+| `onSignedOut(reason)` | `'refresh_rejected' \| 'no_refresh_token'`. |
+| `defaultHeaders` | Extra headers on every call. Any non-simple header makes browsers preflight. |
+| `timeoutMs` | Default 30000; `0` disables. Timeouts reject as `ApiError` with `status: 0`, `code: 'timeout'`. |
+| `crypto` | `OAuthCrypto` `{ getRandomValues(bytes), sha256(data) }` for OAuth PKCE where there is no global WebCrypto (React Native: wrap `expo-crypto`). |
+| `maxRateLimitRetries` | GET replays on 429 honouring `Retry-After` (default 2). Writes are never replayed. |
+
+A refresh that fails because of the network (offline, 5xx) does **not** sign the user out:
+the original 401 is thrown and the session is kept.
+
+## OAuth sign-in (Google / GitHub)
+
+```ts
+const { url, codeVerifier } = await af.auth.oauthStart('google', { returnTo: 'poodleck-console://auth/callback' });
+// open `url` in the browser; keep `codeVerifier` until the redirect comes back
+const ret = parseOAuthReturn(redirectUrl); // { code } | { error } | null
+if (ret && 'code' in ret) await af.auth.oauthComplete({ code: ret.code, codeVerifier });
+```
+
+`returnTo` must be in the server allow-list (400 `return_to_not_allowed`), and the
+server requires the PKCE challenge (400 `pkce_required`). A bad / expired / reused
+code answers 400 `invalid_grant`. On React Native pass the `crypto` option:
+
+```ts
+import * as Crypto from 'expo-crypto';
+new ConsoleClient({ ..., crypto: {
+  getRandomValues: (b) => Crypto.getRandomValues(b),
+  sha256: async (d) => new Uint8Array(await Crypto.digest(Crypto.CryptoDigestAlgorithm.SHA256, d)),
+} });
+```
+
+## Errors
+
+Every failure rejects with `ApiError`: `status` (0 = no response: `network_error` or
+`timeout`), `code` (e.g. `captcha_failed`, `plan_exceeded`, `team_not_publishable`,
+`invalid_config_schema`), `message`, and `details` (the parsed response body).
+
+## Routes
+
+Resource → methods → HTTP route (all JSON, bearer auth unless marked *public*).
+`t` = `forTenant(tenantId)`, `:T` = `/admin/tenants/:tenantId`.
+
+| Resource | Method | Route |
+|---|---|---|
+| `auth` | `register` / `login` (public, store session) | `POST /auth/register` · `POST /auth/login` |
+| | `refresh` | `POST /auth/refresh` |
+| | `logout` | `POST /auth/logout` |
+| | `me` | `GET /auth/me` |
+| | `completeOnboarding` / `reopenOnboarding` | `POST /auth/me/onboarding/complete` · `.../reopen` |
+| | `strategies` (public) | `GET /auth/strategies` |
+| | `oauthStart` (no request) / `oauthComplete` (public, stores session) | URL `GET /auth/:provider?returnTo=&codeChallenge=` · `POST /auth/oauth/exchange` || `tenants` | `listMine` | `GET /me/tenants` |
+| | `create` / `update` | `POST /admin/tenants` · `PATCH /admin/tenants/:id` |
+| `t.members` | `list` / `add` | `GET` / `POST :T/members` |
+| | `updateRole` / `remove` | `PATCH` / `DELETE :T/members/:membershipId` |
+| | `transferOwnership` | `POST :T/members/transfer-ownership` |
+| `t.invites` | `list` / `create` | `GET` / `POST :T/invites` |
+| | `resend` / `revoke` | `POST :T/invites/:id/resend` · `DELETE :T/invites/:id` |
+| `invites` (also on `t`) | `getByToken` / `accept` (public) | `GET /invite/:token` · `POST /invite/:token/accept` |
+| `t.agents` | `list` `create` `get` `update` `delete` `parentTeam` | `:T/agents[/:id[/parent-team]]` (delete = deactivate) |
+| `t.agents.chatTokens` | `list` `create` `update` `revoke` | `:T/agents/:id/chat-tokens[/:token]` |
+| `t.teams` | `list` `create` `get` `update` `delete` | `:T/teams[/:id]` (`list({ excludeTemplateSources })`; teams carry `templateSourceOf`) |
+| | `publication` / `listPublication` / `publish` | `GET :T/teams/:id/publication` · `GET :T/teams/publication` · `POST :T/teams/:id/publish` |
+| `t.teams.humanMembers` | `list` `add` `update` `remove` | `:T/teams/:id/human-members[/:userId]` |
+| `t.variables` | `list` `get` `upsert` `remove` | `GET /tenants/:tid/variables[?q=]` · `GET\|PUT\|DELETE /tenants/:tid/variables/:key` (config has `value`; secrets only `valueHint`) |
+| `t.tools` | `grouped` | `GET /tools/grouped?tenantId=` |
+| `t.connectors` | `directory` / `facets` (sends `X-Tenant-Id`) | `GET /connectors/oauth/directory[/facets]` |
+| | `authorize` | `POST /connectors/oauth/:id/authorize?tenantId=&postAuthRedirect=` |
+| | `saveApiKey` | `POST /connectors/oauth/:id/api-key?tenantId=` |
+| `templates` | `listPublic` / `getPublic` (public) | `GET /public/templates[/:id]` |
+| | `get` / `updateListing` / `listVersions` | `GET` / `PATCH /templates/:id` · `GET /templates/:id/versions` |
+| | `signListingAsset` | `POST /templates/:id/listing-assets/sign` |
+| | `versionHistory` / `diff` | `GET /templates/:id/version-history` · `GET /templates/:id/diff?from=&to=` |
+| | `snapshotDraft` `submitVersion` `reviewVersion` `publishVersion` `discardVersion` `restoreVersion` | `POST /templates/:id/drafts` · `.../versions/:v/{submit,review,publish,restore}` · `DELETE .../versions/:v` |
+| | `linkSource` `unlinkSource` `createSourceCopy` `setReviewPolicy` | `PUT/DELETE /templates/:id/source` · `POST .../source/copy` · `PATCH .../review-policy` |
+| | `configFields` / `setConfigFields` | `GET` / `PUT /templates/:id/config-fields` |
+| `t.templates` (extends `templates`) | `list` | `GET /templates?tenantId=` |
+| | `install` / `installReadiness` | `POST /templates/:id/install` · `GET /templates/:id/install-readiness` |
+| | `saveAgentAsTemplate` / `saveTeamAsTemplate` | `POST :T/{agents,teams}/:id/save-as-template` |
+| | `publishAgentTemplateVersion` / `publishTeamTemplateVersion` | `POST :T/{agents,teams}/:id/publish-template-version` |
+| | `templateSource` | `GET :T/teams/:id/template-source` |
+| | `updatesAvailable` / `updateTeamFromTemplate` / `updateAgentFromTemplate` | `GET /me/template-updates-available` · `POST :T/{teams,agents}/:id/update-from-template` |
+| `marketplace` | `categories` | `GET /marketplace/categories` |
+| `t.apps` | `list` / `get` | `GET /apps[/:id]?tenantId=` |
+| `t.playground` | `list` `get` `create` `finalize` `abort` | `/playgrounds/runs[/:id[/finalize\|abort]]` |
+
+## Not covered (yet)
+
+No `tenants.get` (the server has no `GET /admin/tenants/:id`: read it from `listMine`),
+password
+reset / email verification, Apps write operations, template pricing and earnings,
+skills, trace/activity, the AI designer. They are tracked in the Console SDD.
+
+## Development
+
+```
+npm run build -w @agentforge-io/sdk-console
+npm test -w @agentforge-io/sdk-console        # tsx --test, fake fetch
+npm run typecheck -w @agentforge-io/sdk-console
+```

package/dist/client.d.ts

@@ -0,0 +1,43 @@
+import { HttpCore, type ConsoleClientOptions } from './http';
+import { AgentsResource } from './resources/agents';
+import { AppsResource } from './resources/apps';
+import { AuthResource } from './resources/auth';
+import { ConnectorsResource } from './resources/connectors';
+import { InvitesResource, MembersResource, PublicInvitesResource } from './resources/members';
+import { MarketplaceResource } from './resources/marketplace';
+import { PlaygroundResource } from './resources/playground';
+import { TeamsResource } from './resources/teams';
+import { TemplatesResource, TenantTemplatesResource } from './resources/templates';
+import { TenantsResource } from './resources/tenants';
+import { VariablesResource } from './resources/variables';
+import { ToolsResource } from './resources/tools';
+/** Resources of one workspace. Cheap to create: call `forTenant` per use. */
+export declare class TenantScope {
+    readonly tenantId: string;
+    readonly members: MembersResource;
+    readonly invites: InvitesResource;
+    readonly agents: AgentsResource;
+    readonly teams: TeamsResource;
+    readonly tools: ToolsResource;
+    readonly connectors: ConnectorsResource;
+    readonly templates: TenantTemplatesResource;
+    readonly apps: AppsResource;
+    readonly playground: PlaygroundResource;
+    /** Business data of the workspace (`{{config:KEY}}` / `{{secret:KEY}}`). */
+    readonly variables: VariablesResource;
+    constructor(http: HttpCore, tenantId: string);
+}
+export declare class ConsoleClient {
+    readonly baseURL: string;
+    readonly auth: AuthResource;
+    readonly tenants: TenantsResource;
+    /** Public invite lookups / accept (no workspace needed). */
+    readonly invites: PublicInvitesResource;
+    /** Templates not bound to a workspace: gallery, detail, listing, versions. */
+    readonly templates: TemplatesResource;
+    readonly marketplace: MarketplaceResource;
+    private readonly http;
+    constructor(options: ConsoleClientOptions);
+    /** Bind the `admin/tenants/:tenantId/...` resources to one workspace. */
+    forTenant(tenantId: string): TenantScope;
+}

package/dist/client.js

@@ -0,0 +1,58 @@
+"use strict";
+// ConsoleClient: entry point. One instance per app; `forTenant(id)` binds the
+// workspace-scoped resources.
+//
+//   const af = new ConsoleClient({ baseURL, tokenStore, onSignedOut: () => router.replace('/sign-in') });
+//   await af.auth.login({ email, password });
+//   const { items } = await af.tenants.listMine();
+//   const agents = await af.forTenant(items[0].id).agents.list();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleClient = exports.TenantScope = void 0;
+const http_1 = require("./http");
+const agents_1 = require("./resources/agents");
+const apps_1 = require("./resources/apps");
+const auth_1 = require("./resources/auth");
+const connectors_1 = require("./resources/connectors");
+const members_1 = require("./resources/members");
+const marketplace_1 = require("./resources/marketplace");
+const playground_1 = require("./resources/playground");
+const teams_1 = require("./resources/teams");
+const templates_1 = require("./resources/templates");
+const tenants_1 = require("./resources/tenants");
+const variables_1 = require("./resources/variables");
+const tools_1 = require("./resources/tools");
+/** Resources of one workspace. Cheap to create: call `forTenant` per use. */
+class TenantScope {
+    constructor(http, tenantId) {
+        this.tenantId = tenantId;
+        if (!tenantId)
+            throw new Error('tenantId is required');
+        this.members = new members_1.MembersResource(http, tenantId);
+        this.invites = new members_1.InvitesResource(http, tenantId);
+        this.agents = new agents_1.AgentsResource(http, tenantId);
+        this.teams = new teams_1.TeamsResource(http, tenantId);
+        this.tools = new tools_1.ToolsResource(http, tenantId);
+        this.connectors = new connectors_1.ConnectorsResource(http, tenantId);
+        this.templates = new templates_1.TenantTemplatesResource(http, tenantId);
+        this.apps = new apps_1.AppsResource(http, tenantId);
+        this.playground = new playground_1.PlaygroundResource(http, tenantId);
+        this.variables = new variables_1.VariablesResource(http, tenantId);
+    }
+}
+exports.TenantScope = TenantScope;
+class ConsoleClient {
+    constructor(options) {
+        this.http = new http_1.HttpCore(options);
+        this.baseURL = this.http.baseURL;
+        this.auth = new auth_1.AuthResource(this.http);
+        this.tenants = new tenants_1.TenantsResource(this.http);
+        this.invites = new members_1.PublicInvitesResource(this.http);
+        this.templates = new templates_1.TemplatesResource(this.http);
+        this.marketplace = new marketplace_1.MarketplaceResource(this.http);
+    }
+    /** Bind the `admin/tenants/:tenantId/...` resources to one workspace. */
+    forTenant(tenantId) {
+        return new TenantScope(this.http, tenantId);
+    }
+}
+exports.ConsoleClient = ConsoleClient;

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+export declare class ApiError extends Error {
+    /** HTTP status. `0` = the request never got a response (offline, DNS,
+     *  timeout, aborted): see `code` (`network_error` | `timeout`). */
+    readonly status: number;
+    /** Machine-readable code from the body (`{ code }`, or a code-shaped
+     *  `{ error }`), e.g. `captcha_failed`, `plan_exceeded`, `team_not_publishable`. */
+    readonly code?: string;
+    /** Parsed JSON body when the response had one, otherwise the raw text. */
+    readonly details?: unknown;
+    readonly cause?: unknown;
+    constructor(init: {
+        status: number;
+        message: string;
+        code?: string;
+        details?: unknown;
+        cause?: unknown;
+    });
+    get isNetworkError(): boolean;
+    get isUnauthorized(): boolean;
+    get isForbidden(): boolean;
+    get isNotFound(): boolean;
+}
+export declare function isApiError(err: unknown): err is ApiError;
+/** Map a non-2xx response (body already read as text) to an ApiError. */
+export declare function errorFromResponse(status: number, statusText: string, text: string): ApiError;

package/dist/errors.js

@@ -0,0 +1,93 @@
+"use strict";
+// Typed error every failed request rejects with. Branch on `status` / `code`;
+// `details` carries the parsed response body (e.g. `{ issues }` of a 409
+// `team_not_publishable`, `{ usage }` of a 402 `plan_exceeded`).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiError = void 0;
+exports.isApiError = isApiError;
+exports.errorFromResponse = errorFromResponse;
+class ApiError extends Error {
+    constructor(init) {
+        super(init.message);
+        this.name = 'ApiError';
+        this.status = init.status;
+        this.code = init.code;
+        this.details = init.details;
+        this.cause = init.cause;
+    }
+    get isNetworkError() {
+        return this.status === 0;
+    }
+    get isUnauthorized() {
+        return this.status === 401;
+    }
+    get isForbidden() {
+        return this.status === 403;
+    }
+    get isNotFound() {
+        return this.status === 404;
+    }
+}
+exports.ApiError = ApiError;
+function isApiError(err) {
+    return err instanceof ApiError;
+}
+// `captcha_failed` / `INVALID_MAPPING` style, plus snake_case. Nest's status
+// text ("Bad Request") matches neither, so it is never mistaken for a code.
+const CODE_SHAPE = /^(?:[A-Z][A-Z0-9_]+|[a-z][a-z0-9]*(?:_[a-z0-9]+)+)$/;
+// A `reason` is a deliberate machine value, so it is accepted looser than `error`
+// (which may be Nest's status text): one token, no spaces (`forbidden`, `team_not_found`).
+const REASON_SHAPE = /^[A-Za-z][A-Za-z0-9_.:-]{0,79}$/;
+function messageOf(value) {
+    if (typeof value === 'string' && value)
+        return value;
+    if (Array.isArray(value)) {
+        const parts = value.filter((v) => typeof v === 'string');
+        return parts.length ? parts.join('; ') : undefined;
+    }
+    if (value && typeof value === 'object') {
+        return messageOf(value.message);
+    }
+    return undefined;
+}
+/** Map a non-2xx response (body already read as text) to an ApiError. */
+function errorFromResponse(status, statusText, text) {
+    let parsed = text || undefined;
+    if (text) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            /* not JSON: keep the raw text */
+        }
+    }
+    let code;
+    let message;
+    if (parsed && typeof parsed === 'object') {
+        const body = parsed;
+        if (typeof body.code === 'string')
+            code = body.code;
+        // Some routes send `{ reason: 'invalid_config_schema', message }`: `code` falls back to `reason`.
+        else if (typeof body.reason === 'string' && REASON_SHAPE.test(body.reason))
+            code = body.reason;
+        else if (typeof body.error === 'string' && CODE_SHAPE.test(body.error))
+            code = body.error;
+        else if (body.message && typeof body.message === 'object') {
+            const nested = body.message;
+            if (typeof nested.code === 'string')
+                code = nested.code;
+            else if (typeof nested.reason === 'string' && REASON_SHAPE.test(nested.reason))
+                code = nested.reason;
+        }
+        message = messageOf(body.message) ?? (typeof body.error === 'string' ? body.error : undefined);
+    }
+    else if (typeof parsed === 'string' && parsed.length < 300) {
+        message = parsed;
+    }
+    return new ApiError({
+        status,
+        message: message ?? (statusText ? `HTTP ${status} ${statusText}` : `HTTP ${status}`),
+        code,
+        details: parsed,
+    });
+}

package/dist/http.d.ts

@@ -0,0 +1,76 @@
+import type { OAuthCrypto } from './oauth';
+import type { AuthTokens, TokenStore } from './token-store';
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Why the session ended without the user asking for it. */
+export type SignedOutReason = 'refresh_rejected' | 'no_refresh_token';
+export interface ConsoleClientOptions {
+    /** Platform base URL, e.g. `https://api.agentforge.example`. */
+    baseURL: string;
+    /** Where access + refresh tokens live. */
+    tokenStore: TokenStore;
+    /** Override fetch (RN polyfills, tests, custom transports). Defaults to the global one. */
+    fetch?: FetchLike;
+    /** Called after the session could not be salvaged (refresh rejected, or no
+     *  refresh token): the token store is already cleared. Route to sign-in here.
+     *  NOT called for an explicit `auth.logout()`. */
+    onSignedOut?: (reason: SignedOutReason) => void;
+    /** Headers added to every request (e.g. `ngrok-skip-browser-warning`). Note
+     *  that any non-simple header makes browsers send a CORS preflight. */
+    defaultHeaders?: Record<string, string>;
+    /** Abort a request after this many ms. Default 30000; `0` disables. */
+    timeoutMs?: number;
+    /** Replays of a GET answered 429, honouring `Retry-After`. Default 2. */
+    maxRateLimitRetries?: number;
+    /** Crypto adapter for OAuth PKCE (`auth.oauthStart`). Only needed where there
+     *  is no global WebCrypto (`crypto.getRandomValues` + `crypto.subtle.digest`),
+     *  i.e. React Native: pass an `expo-crypto` based one. */
+    crypto?: OAuthCrypto;
+    /** Sleep used between 429 replays. Injectable for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export type QueryValue = string | number | boolean | null | undefined | ReadonlyArray<string | number>;
+export interface RequestOptions {
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    /** Extra headers for this call (e.g. `X-Tenant-Id`). */
+    headers?: Record<string, string>;
+    /** `false` = public route: no Authorization header, never refreshes. */
+    auth?: boolean;
+}
+/** Join a query object: skips null/undefined, arrays become `a,b`. */
+export declare function buildQuery(query?: Record<string, QueryValue>): string;
+export declare function seg(value: string): string;
+export declare class HttpCore {
+    readonly baseURL: string;
+    readonly crypto?: OAuthCrypto;
+    private readonly store;
+    private readonly opts;
+    private refreshing;
+    private signingOut;
+    /** Bumped whenever the session is replaced or wiped; a refresh that started under an older epoch is stale. */
+    private epoch;
+    constructor(opts: ConsoleClientOptions);
+    /** Authenticated (or `auth: false`) JSON request. Resolves `undefined` on 204 / empty body. */
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /** Persist a session obtained from login / register / invite accept. */
+    setSession(tokens: AuthTokens): Promise<void>;
+    /** Invalidate any in-flight refresh without touching the store (call before
+     *  an auth call that will replace or wipe the session). */
+    beginSessionChange(): void;
+    /** Wipe the session without firing `onSignedOut` (explicit logout). */
+    clearSession(): Promise<void>;
+    /** Force a refresh now (shares the in-flight one). Throws if it does not succeed. */
+    refreshNow(): Promise<AuthTokens>;
+    private send;
+    /** @returns true when the request should be replayed once. */
+    private recoverFrom401;
+    /** Idempotent: waiters of the same failed refresh all land here, but only
+     *  one tears the session down and fires the callback. */
+    private signOut;
+    /** One /auth/refresh at a time: a burst of 401s awaits the same promise.
+     *  The refresh token rotates on use, so a second concurrent call would be
+     *  read as token reuse by the server and revoke the family. */
+    private refreshSingleFlight;
+    private doRefresh;
+    private rawFetch;
+}