@flowy-agent-store/client 0.1.0-beta.6 → 0.1.0-beta.8

package/dist/index.cjs

@@ -276,7 +276,7 @@ var WebSocketTransport = class {
 /** Header the server mints the per-call connection id under. */
 const CONNECTION_HEADER = "x-app-server-connection-id";
 /** Protocol version this binding announces on the one-shot handshake. */
-const PROTOCOL_VERSION = "fp-7";
+const PROTOCOL_VERSION = "fp-12";
 /**
 * Protocol method → REST route. Verified from handler bodies, not from the
 * route list (a route existing does not prove which method it mirrors).
@@ -471,6 +471,26 @@ const HTTP_ROUTES = {
 		path: "/connectors/:connector_id/auth-logout",
 		source: "connector_auth_logout_route() -> connector_auth_logout_impl"
 	},
+	"connector/credential/get": {
+		verb: "GET",
+		path: "/connectors/:connector_id/credential",
+		source: "connector_credential_get_route() -> connector_credential_get_impl"
+	},
+	"connector/credential/set": {
+		verb: "POST",
+		path: "/connectors/:connector_id/credential",
+		source: "connector_credential_set_route() -> connector_credential_set_impl"
+	},
+	"connector/credential/clear": {
+		verb: "POST",
+		path: "/connectors/:connector_id/credential/clear",
+		source: "connector_credential_clear_route() -> connector_credential_clear_impl"
+	},
+	"connector/register": {
+		verb: "POST",
+		path: "/connectors",
+		source: "register_connector_route() -> register_connector_impl"
+	},
 	"import/run": {
 		verb: "POST",
 		path: "/imports",
@@ -560,6 +580,11 @@ const HTTP_ROUTES = {
 		verb: "POST",
 		path: "/store/:marketplace_id/entries/:entry_name/install",
 		source: "store_install_entry_route() -> store_install_entry_impl"
+	},
+	"store/update-entry": {
+		verb: "POST",
+		path: "/store/:marketplace_id/entries/:entry_name/update",
+		source: "store_update_entry_route() -> store_update_entry_impl"
 	}
 };
 /** Methods that are WebSocket-only by design — named so the error explains itself. */
@@ -781,6 +806,19 @@ var AgentClient = class {
 	get(agentId) {
 		return this.transport.request("agent/get", { agent_id: agentId });
 	}
+	/**
+	* Export one AgentDefinition as a portable {@link ExpertPack}.
+	*
+	* Requires WebSocket: like the rest of this family, `agent/export` has no HTTP
+	* route. The expert must be installed and enabled, or the host answers
+	* `agent_not_installed` / `agent_disabled`; a host whose `[expert_export]`
+	* table refuses the id answers `policy_denied`. Check
+	* `capabilities.expert_export` for the *seam* — it does not promise this id is
+	* exportable.
+	*/
+	export(agentId) {
+		return this.transport.request("agent/export", { agent_id: agentId });
+	}
 };
 //#endregion
 //#region src/conversations.ts
@@ -1067,6 +1105,13 @@ var ConversationSubscription = class {
 };
 //#endregion
 //#region src/connectors.ts
+/**
+* How long {@link ConnectorClient.waitForAuth} waits by default: the host's own
+* callback window is 120s, so a shorter client budget would give up on flows the
+* host is still willing to finish.
+*/
+const DEFAULT_AUTH_TIMEOUT_MS = 12e4;
+const DEFAULT_AUTH_POLL_MS = 500;
 var ConnectorClient = class {
 	transport;
 	constructor(transport) {
@@ -1100,17 +1145,117 @@ var ConnectorClient = class {
 	test(connectorId) {
 		return this.transport.request("connector/test", { connector_id: connectorId });
 	}
-	/** Check the current OAuth state for a connector. */
+	/**
+	* Check the current OAuth state for a connector.
+	*
+	* Read `error` too: a flow that failed after the browser step is reported as
+	* `state: "not_authenticated"` **plus** `error`, because the wire has no
+	* failing state to flip to. {@link waitForAuth} is the loop that does this.
+	*/
 	authStatus(connectorId) {
 		return this.transport.request("connector/auth/status", { connector_id: connectorId });
 	}
 	/**
+	* The credential form a connector needs filled in, as **this caller** sees it
+	* (doc `34` §6.1).
+	*
+	* `mode` says which kind of authentication applies (`none` / `oauth` / `token`),
+	* `status` whether anything is still missing, and `missing` names the keys.
+	* `fields` is everything needed to render the form — labels, placeholders,
+	* descriptions and the marketplace's "where do I get a key" link, in both
+	* languages. No secret ever comes back: only `plain` fields carry a `value`.
+	*/
+	credentials(connectorId) {
+		return this.transport.request("connector/credential/get", { connector_id: connectorId });
+	}
+	/**
+	* Store what the user typed and get the new state back.
+	*
+	* Only keys the connector's own declaration names are accepted — the form is
+	* the whole write surface. `secret` fields go to the host's credential store
+	* under the caller's own namespace, `plain` fields into the connector's
+	* configuration, so a shared host never resolves one user's token for another.
+	*/
+	setCredentials(connectorId, values) {
+		return this.transport.request("connector/credential/set", {
+			connector_id: connectorId,
+			values
+		});
+	}
+	/**
+	* Forget stored credentials. `keys` omitted = every secret field of this
+	* connector. Idempotent: clearing what is not there succeeds.
+	*/
+	clearCredentials(connectorId, keys) {
+		return this.transport.request("connector/credential/clear", {
+			connector_id: connectorId,
+			...keys ? { keys } : {}
+		});
+	}
+	/**
+	* Register a connector this host never imported — your own MCP server, handed
+	* over together with the template that says what it needs (doc `34` §6.5).
+	*
+	* The **template is the whole declaration**: whatever `${secret:NAME}` the URL,
+	* headers or env name becomes that connector's credential form, so there is no
+	* `token-schema.json` to ship and nothing to install from a marketplace. The
+	* connector's own non-secret settings travel in `values`.
+	*
+	* Secrets do **not** travel here: hand them over with {@link setCredentials},
+	* which keeps exactly one write surface for values. The returned detail already
+	* carries the credential block, so `missing` tells you which keys are still
+	* needed.
+	*
+	* Re-registering the same name updates it; a builtin server's name is refused.
+	* The row is created **disabled** — enabling it still requires a probe that
+	* passes — and this method is on the installation-owner-only surface, because
+	* choosing where the host reaches is the owner's call.
+	*/
+	register(registration) {
+		return this.transport.request("connector/register", registration);
+	}
+	/**
 	* Kick off the OAuth browser flow on the trusted host. Returns the start
-	* acknowledgement immediately; poll `authStatus` until `authenticated`.
+	* acknowledgement immediately; follow it with {@link waitForAuth}.
+	*
+	* `state: "error"` here is a failure that happened **before** the browser was
+	* opened (endpoint discovery, client identity, binding the callback, launching
+	* the browser): nothing was shown to the user, so `error` is the whole story
+	* and there is nothing to wait for.
 	*/
 	authStart(connectorId) {
 		return this.transport.request("connector/auth/start", { connector_id: connectorId });
 	}
+	/**
+	* Wait for an authorization that was started (in the browser, or by a
+	* previous `authStart`) to finish — and **report why** when it does not.
+	*
+	* A hand-rolled `while (state !== "authenticated") poll()` loop ends in "it
+	* never became authenticated", with the reason sitting unread in the status it
+	* already fetched: a token exchange the authorization server refused (a
+	* throttling gateway answers `slow_down`), a callback timeout, a CSRF/path
+	* mismatch. Those land in `authStatus().error` *only*, and the state stays
+	* `not_authenticated` — there is no failing state on the wire.
+	*
+	* Resolves for every domain outcome (`authenticated` / `error` / `timeout`);
+	* rejects only when the status read itself fails (transport or protocol), the
+	* same rule as `connector/call`. The wait is bounded by `timeoutMs`; a caller
+	* that needs to stop earlier can race the returned promise.
+	*/
+	async waitForAuth(connectorId, options = {}) {
+		const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_AUTH_TIMEOUT_MS);
+		const pollMs = options.pollMs ?? DEFAULT_AUTH_POLL_MS;
+		for (;;) {
+			const status = await this.authStatus(connectorId);
+			if (status.state === "authenticated") return { state: "authenticated" };
+			if (status.error) return {
+				state: "error",
+				error: status.error
+			};
+			if (Date.now() >= deadline) return { state: "timeout" };
+			await new Promise((resolve) => setTimeout(resolve, pollMs));
+		}
+	}
 	/** Revoke the OAuth token for a connector. */
 	logout(connectorId) {
 		return this.transport.request("connector/auth/logout", { connector_id: connectorId }).then(() => void 0);
@@ -1530,6 +1675,7 @@ var StoreError = class extends Error {
 const DEFAULT_READY_TIMEOUT_MS = 3e4;
 const DEFAULT_READY_POLL_MS = 400;
 const DEFAULT_READY_POLL_MAX_MS = 4e3;
+const DEFAULT_READY_PROBE_MS = 5e3;
 /** Every string a `LocalizedText` carries, for haystack building. */
 function localizedValues(text) {
 	if (typeof text === "string") return [text];
@@ -1571,11 +1717,13 @@ var StoreClient = class {
 	readyTimeoutMs;
 	readyPollMs;
 	readyPollMaxMs;
+	readyProbeMs;
 	constructor(host, options = {}) {
 		this.host = host;
 		this.readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
 		this.readyPollMs = options.readyPollMs ?? DEFAULT_READY_POLL_MS;
 		this.readyPollMaxMs = options.readyPollMaxMs ?? DEFAULT_READY_POLL_MAX_MS;
+		this.readyProbeMs = options.readyProbeMs ?? DEFAULT_READY_PROBE_MS;
 	}
 	/** Every item across enabled marketplaces, with install state. */
 	async list() {
@@ -1607,15 +1755,45 @@ var StoreClient = class {
 	/**
 	* What a caller can offer for an item's pending update.
 	*
-	* `"none"` means there is nothing to do; `"uninstall_reinstall"` means the
-	* entry is installed at a different version and the only path the wire offers
-	* is to release it and install again (the version-aware re-import then picks
-	* up the current version). `"unknown"` is returned rather than guessing when
-	* the item carries no snapshot to release.
+	* `"none"` means there is nothing to do; `"update"` means the entry is
+	* installed at a different version and `update()` is the action that lands it
+	* (`store/update-entry`, `36` D3); `"unknown"` is returned rather than
+	* guessing when the item carries no snapshot to replace.
 	*/
 	updateHint(item) {
 		if (!item.installed || !item.update_available) return "none";
-		return item.snapshot_id ? "uninstall_reinstall" : "unknown";
+		return item.snapshot_id ? "update" : "unknown";
+	}
+	/**
+	* Upgrade an installed item to the version its marketplace advertises.
+	*
+	* The host does the ordering: new version installed first, previous one
+	* released only when that succeeded. So a failure resolves `ok: false` with
+	* the previous installation still in place (`releasedCount === 0`) — the
+	* caller never has to reason about a half-upgraded item.
+	*
+	* Refuses before the round trip when there is nothing to replace: an item that
+	* is not installed (`not_installed`) or is already current is not a failure of
+	* *this* call, and `updateHint()` is the way to ask first.
+	*/
+	async update(item, options = {}) {
+		this.assertUsable(item, options.signal);
+		this.requireSnapshot(item);
+		const result = await this.host.updateStoreEntry(item.marketplace_id, item.entry_name);
+		const components = result.outcomes ?? [];
+		const outcome = {
+			snapshotId: result.snapshot_id,
+			reused: result.reused,
+			components,
+			ok: result.errors.length === 0 && components.every((component) => component.ok),
+			errors: result.errors,
+			warnings: result.warnings,
+			fromVersion: result.previous_version ?? void 0,
+			toVersion: result.version,
+			releasedCount: result.released_count ?? 0
+		};
+		if (options.waitForReady === false) return outcome;
+		return this.awaitReady(outcome, options);
 	}
 	/**
 	* Import (when needed) and install one store item, then wait until it is
@@ -1629,7 +1807,9 @@ var StoreClient = class {
 			snapshotId: result.snapshot_id,
 			reused: result.reused,
 			components,
-			ok: result.errors.length === 0 && components.every((component) => component.ok)
+			ok: result.errors.length === 0 && components.every((component) => component.ok),
+			errors: result.errors,
+			warnings: result.warnings
 		};
 		if (options.waitForReady === false) return outcome;
 		return this.awaitReady(outcome, options);
@@ -1648,7 +1828,9 @@ var StoreClient = class {
 			snapshotId,
 			reused: true,
 			components: [],
-			ok: true
+			ok: true,
+			errors: [],
+			warnings: []
 		};
 		const status = await this.host.uninstallInstall(snapshotId, componentIds);
 		return this.outcomeFromStatus(snapshotId, status, false);
@@ -1668,7 +1850,9 @@ var StoreClient = class {
 			snapshotId,
 			reused: true,
 			components: [],
-			ok: true
+			ok: true,
+			errors: [],
+			warnings: []
 		};
 		const status = enabled ? await this.host.enableInstall(snapshotId, componentIds) : await this.host.disableInstall(snapshotId, componentIds);
 		return this.outcomeFromStatus(snapshotId, status, false);
@@ -1687,11 +1871,14 @@ var StoreClient = class {
 	}
 	outcomeFromStatus(snapshotId, status, reused) {
 		const components = status.outcomes ?? [];
+		const errors = status.errors ?? [];
 		return {
 			snapshotId,
 			reused,
 			components,
-			ok: (status.errors ?? []).length === 0 && components.every((component) => component.ok)
+			ok: errors.length === 0 && components.every((component) => component.ok),
+			errors,
+			warnings: []
 		};
 	}
 	/**
@@ -1709,11 +1896,15 @@ var StoreClient = class {
 		if (connectors.length > 0) await this.host.enableInstall(snapshotId, connectors.map((component) => component.id));
 		const deadline = Date.now() + (options.timeoutMs ?? this.readyTimeoutMs);
 		let interval = this.readyPollMs;
+		let nextProbeAt = 0;
 		let last = status.components;
 		for (;;) {
+			const now = Date.now();
+			const allowProbe = now >= nextProbeAt;
+			if (allowProbe) nextProbeAt = now + this.readyProbeMs;
 			const blocked = (await Promise.all(last.filter((component) => component.state !== "not-installed").map(async (component) => ({
 				component,
-				verdict: await this.readiness(component)
+				verdict: await this.readiness(component, allowProbe)
 			})))).find((entry) => !entry.verdict.ready);
 			if (!blocked) return {
 				...outcome,
@@ -1743,8 +1934,12 @@ var StoreClient = class {
 	* unknown kind is reported ready rather than blocking: this layer cannot judge
 	* a component it does not understand, and a false timeout on a future kind
 	* would be worse than passing it through.
+	*
+	* `allowProbe` gates the one kind whose readiness needs a real connection (a
+	* connector); the other kinds answer from local reads, so the cadence does not
+	* apply to them.
 	*/
-	async readiness(component) {
+	async readiness(component, allowProbe) {
 		try {
 			switch (component.kind) {
 				case "skill": return (await this.host.skills.list()).some((skill) => skill.name === component.name) ? { ready: true } : { ready: false };
@@ -1753,8 +1948,9 @@ var StoreClient = class {
 					await this.host.teams.get(component.id);
 					return { ready: true };
 				case "connector": {
-					if ((await this.host.connectors.test(component.id)).success) return { ready: true };
+					if (allowProbe && (await this.host.connectors.test(component.id)).success) return { ready: true };
 					const status = await this.host.connectors.status(component.id);
+					if (status.status === "connected") return { ready: true };
 					if (status.status === "authorization_required" || status.status === "reauthorization_required") return {
 						ready: false,
 						terminal: "authorization_required"
@@ -1783,6 +1979,21 @@ var TeamClient = class {
 	get(teamId) {
 		return this.transport.request("team/get", { team_id: teamId });
 	}
+	/**
+	* Export one TeamDefinition as a portable {@link ExpertPack}, with every member
+	* expanded and the **leader first**.
+	*
+	* All-or-nothing: if any member is uninstalled, disabled, or refused by the
+	* host's `[expert_export]` table, the whole call fails rather than returning a
+	* partial roster — the same posture `team/run` takes before it creates
+	* anything. `teamVersion` is an optional pin; a mismatch is `version_mismatch`.
+	*/
+	export(teamId, teamVersion) {
+		return this.transport.request("team/export", {
+			team_id: teamId,
+			team_version: teamVersion
+		});
+	}
 };
 //#endregion
 //#region src/models.ts
@@ -2026,6 +2237,20 @@ var AppServerClient = class {
 			entry_name: entryName
 		});
 	}
+	/**
+	* Upgrade an installed entry to the version its marketplace advertises.
+	*
+	* The host installs the new version before releasing the old one, so a failure
+	* leaves the previous installation usable (`released_count: 0` is the machine
+	* readable form of that). Refused for an entry that is not installed — this is
+	* never a second way to install something.
+	*/
+	async updateStoreEntry(marketplaceId, entryName) {
+		return this.transport.request("store/update-entry", {
+			marketplace_id: marketplaceId,
+			entry_name: entryName
+		});
+	}
 };
 //#endregion
 //#region src/conversation-handle.ts