@tai42/api-client 1.3.0 → 1.5.0

package/src/schemas.ts

@@ -490,6 +490,25 @@ export const manifestView = z.object({
   mcp: z.array(manifestMcpEntry),
   user_tools: z.array(z.string()),
 });
+
+/**
+ * One `!ENV ${VAR[:default]}` marker the manifest's MCP section carries
+ * (`GET /api/manifest/mcp-env-refs`) — NAMES and BOOLEANS only, NEVER values.
+ * `pointer` is the RFC 6901 json-pointer of the leaf (`/mcp/<i>/config/...`);
+ * `has_default` is whether the marker carries a `:default`; `set` is whether the
+ * var resolves in the EFFECTIVE env (the resolution truth the install-time
+ * dangling refusal reads), so a var supplied by the deployment shows green, never
+ * a false red. The checklist derives from THIS alone — no env value is ever fetched.
+ */
+export const mcpEnvRef = z.object({
+  var: z.string(),
+  pointer: z.string(),
+  has_default: z.boolean(),
+  set: z.boolean(),
+});
+export type McpEnvRef = z.infer<typeof mcpEnvRef>;
+export const mcpEnvRefs = z.array(mcpEnvRef);
+export type McpEnvRefs = z.infer<typeof mcpEnvRefs>;
 /**
  * The apply result every config-writer mutation returns (`POST /api/mcp-config`,
  * `POST /api/config/env`): the serving worker's local reload result (`status` +
@@ -784,7 +803,7 @@ export const connectionsList = z.object({
   total: z.number(),
   // Count of connections whose `auth_health_state` is not healthy across the whole
   // set (independent of any filter/limit) — the attention-badge count. Optional:
-  // no UI consumes it this mission, and an older worker mid-rollout omits it.
+  // no UI consumes it, and an older worker mid-rollout omits it.
   unhealthy: z.number().optional(),
 });
 
@@ -1805,26 +1824,52 @@ export type RunTrace = z.infer<typeof runTrace>;
 // -- marketplace -------------------------------------------------------------
 
 /**
- * One contained item of a marketplace plugin (a searchable row): its kind
- * (tool / agent / extension / …), name, description, and free-form tags.
+ * One contained item of a marketplace plugin's published version: its kind
+ * (tool / agent / extension / …), name, description, free-form tags, and the
+ * logical group it belongs to (`null` when ungrouped).
  */
 export const marketplaceItem = z.object({
   kind: z.string(),
   name: z.string(),
   description: z.string(),
   tags: z.array(z.string()),
+  group: z.string().nullable(),
 });
 export type MarketplaceItem = z.infer<typeof marketplaceItem>;
 
 /**
- * One item-level search row (`GET /api/marketplace/search`): the contained item
- * plus the listing it belongs to. `ref` is the "namespace/name" install target
- * (install targets the LISTING), so every row carries enough to group under and
- * link to its plugin. `latest_version` is nullable defensively; the search
- * relation only emits listings with a published version.
+ * One kind summary of a search row: an item kind, how many UNGROUPED items of
+ * that kind the listing's latest published version carries, and their names.
+ * The registry orders the array count DESC then kind ASC, and each entry's
+ * `names` ASC; the UI renders in that order.
+ */
+export const marketplaceSearchKind = z.object({
+  kind: z.string(),
+  count: z.number(),
+  names: z.array(z.string()),
+});
+export type MarketplaceSearchKind = z.infer<typeof marketplaceSearchKind>;
+
+/**
+ * One logical group of a search row: the group name and how many items the
+ * listing's latest published version places in it. The registry orders the
+ * array count DESC then name ASC; the UI renders in that order.
+ */
+export const marketplaceSearchGroup = z.object({
+  name: z.string(),
+  count: z.number(),
+});
+export type MarketplaceSearchGroup = z.infer<typeof marketplaceSearchGroup>;
+
+/**
+ * One listing-level search row (`GET /api/marketplace/search`). `ref` is the
+ * "namespace/name" install target, so every row carries enough to link to its
+ * plugin. `latest_version` is nullable defensively; the search relation only
+ * emits listings with a published version. `kinds` summarizes that latest
+ * version's UNGROUPED items; `groups` summarizes its logical groups (`[]` when
+ * none). Both keys are always present.
  */
 export const marketplaceSearchRow = z.object({
-  item: marketplaceItem,
   ref: z.string(),
   namespace: z.string(),
   name: z.string(),
@@ -1836,18 +1881,23 @@ export const marketplaceSearchRow = z.object({
   tags: z.array(z.string()),
   trust_tier: z.string(),
   pricing: z.string(),
+  // A display-only premium flag: a badge, never a payment surface. Nullable
+  // + optional: an older registry omits it, and it is absent on non-premium rows.
+  premium: z.boolean().nullish(),
   latest_version: z.string().nullable(),
   downloads: z.number(),
   updated_at: z.string(),
+  kinds: z.array(marketplaceSearchKind),
+  groups: z.array(marketplaceSearchGroup),
 });
 export type MarketplaceSearchRow = z.infer<typeof marketplaceSearchRow>;
 
 /**
- * One page of search rows. The wire carries no next-page field — has-next is
+ * One page of listing rows. The wire carries no next-page field — has-next is
  * COMPUTED: `page * page_size < total`.
  */
 export const marketplaceSearchPage = z.object({
-  items: z.array(marketplaceSearchRow),
+  listings: z.array(marketplaceSearchRow),
   total: z.number(),
   page: z.number(),
   page_size: z.number(),
@@ -1869,11 +1919,35 @@ export const marketplaceVersion = z.object({
 export type MarketplaceVersion = z.infer<typeof marketplaceVersion>;
 
 /**
- * The listing's latest published version as embedded in its detail: the version
- * plus the items that version contains.
+ * The listing's latest published version as embedded in its detail: the version,
+ * the items it contains, and a minimal typed passthrough of the published spec.
+ *
+ * `spec` is carried so the install dialog can read an mcp-server item's public
+ * `mcp.env` marker strings (`provides[].mcp.env`) and collect its required `!ENV`
+ * vars before install. Only that path is typed; everything else on the spec is
+ * `.passthrough()`-preserved but unmodelled (zod would otherwise strip the whole
+ * `spec` as an unknown key). Nullable + optional: a listing with nothing published
+ * carries no spec.
  */
 export const marketplaceLatestVersion = marketplaceVersion.extend({
   items: z.array(marketplaceItem),
+  spec: z
+    .object({
+      provides: z.array(
+        z
+          .object({
+            kind: z.string(),
+            name: z.string(),
+            mcp: z
+              .object({ env: z.record(z.string(), z.string()).nullish() })
+              .passthrough()
+              .nullish(),
+          })
+          .passthrough(),
+      ),
+    })
+    .passthrough()
+    .nullish(),
 });
 export type MarketplaceLatestVersion = z.infer<typeof marketplaceLatestVersion>;
 
@@ -1907,10 +1981,15 @@ export const marketplacePluginDetail = z.object({
   license: z.string().nullable(),
   homepage_url: z.string().nullable(),
   repository_url: z.string().nullable(),
+  // The marketplace-stored docs-site URL: the store is the source, the UI a
+  // link. Nullable + optional: absent on a listing with no published docs.
+  docs_url: z.string().nullish(),
   categories: z.array(z.string()),
   tags: z.array(z.string()),
   trust_tier: z.string(),
   pricing: z.string(),
+  // A display-only premium flag: a badge, never a payment surface.
+  premium: z.boolean().nullish(),
   downloads: z.number(),
   latest: marketplaceLatestVersion.nullable(),
   versions: z.array(marketplaceVersion),
@@ -1954,6 +2033,10 @@ export const marketplaceInstalledPlugin = z
     incompatible_newer: z.string().nullable(),
     missing_upstream: z.boolean(),
     compat: marketplaceInstalledCompat,
+    // The `{kind, name}` of every item this plugin's stored spec provides
+    // (local truth). The McpTab joins the mcp-server item names against the
+    // manifest's mcp-entry titles to render an installer-written entry read-only.
+    items: z.array(marketplaceItem.pick({ kind: true, name: true })),
   })
   .strict();
 export type MarketplaceInstalledPlugin = z.infer<typeof marketplaceInstalledPlugin>;