busabase-sdk 0.18.0 → 0.19.0

package/dist/airapp.d.ts

@@ -1,4 +1,4 @@
-import { t as BusabaseClient } from "./client-CbUceGzy.js";
+import { t as BusabaseClient } from "./client-slzL_ils.js";
 //#region src/airapp.d.ts
 type NodeChangeRequestInput = Parameters<BusabaseClient["nodes"]["createChangeRequest"]>[0];
 type NodeOperationInput = NodeChangeRequestInput["operations"][number];
@@ -87,6 +87,15 @@ interface AirAppResourceConfig {
 /**
  * The ownership stamp written into `node.metadata`.
  *
+ * Structurally identical to (and kept in lockstep with) the contract package's
+ * `AppResourceOwnership`, which `busabase-package`'s installer writes for the
+ * SAME resources when a user installs the app from the Template Center instead
+ * of running its `setup.mjs`. The two writers only recognise each other's work
+ * by this shape — drift means a user who installed through the UI and then ran
+ * the skill in their shell hits `SETUP_CONFLICT` on their own data. The
+ * assertion below is what makes that drift a compile error rather than a
+ * support ticket.
+ *
  * A type alias rather than an `interface` on purpose: `nodes.updateMetadata`
  * and the create operations take `Record<string, unknown>`, and an interface —
  * being open to declaration merging — is not assignable to an index signature.

package/dist/airapp.js

@@ -1,5 +1,155 @@
+import { z } from "zod";
+const TemplateAirAppRefSchema = z.object({
+	/** Slug of the `content/<dir>` holding the AirApp. */
+	slug: z.string().min(1),
+	role: z.enum([
+		"primary",
+		"admin",
+		"public",
+		"tool"
+	]),
+	label: z.string().optional()
+});
+/**
+* Secrets the app expects to find in the Vault.
+*
+* DECLARED, never created: the package format has no slot for secret values and
+* must not grow one (the same "you cannot leak what the format cannot express"
+* rule the whole format is built on). Install surfaces these as a post-install
+* prompt; the user fills them in the Vault themselves.
+*/
+const TemplateSecretSchema = z.object({
+	key: z.string().min(1),
+	description: z.string().default(""),
+	required: z.boolean().default(true)
+});
+z.object({
+	/** Template Center category, e.g. `"crm"`, `"email"`, `"content"`. */
+	category: z.string().min(1),
+	tags: z.array(z.string()).default([]),
+	/** Card/detail screenshots, package-relative (`assets/screenshots/overview.webp`). */
+	screenshots: z.array(z.string()).default([]),
+	/**
+	* Ready-made prompts shown after install ("Ask agent" prefills the first).
+	*
+	* They are the difference between a folder of tables and something a user can
+	* *use*: the point of a template is that the agent already knows the job, and
+	* these are how that is made visible rather than left for the user to guess.
+	*/
+	agentPrompts: z.array(z.string()).default([]),
+	/** Single-AirApp shorthand. Mutually exclusive with `airapps`. */
+	airapp: z.string().optional(),
+	/** Multi-AirApp form. Exactly one entry must have `role: "primary"`. */
+	airapps: z.array(TemplateAirAppRefSchema).optional(),
+	/**
+	* Bumped by the author when the declared resource shape changes.
+	*
+	* Part of the ownership stamp, so BOTH doors must agree on it: the installer
+	* writes it, and a skill's own `setup.mjs` compares against it to decide
+	* whether a node it finds is its own current shape or an older one to repair.
+	* Defaulted rather than required so an author who never versions their app
+	* still gets a stamp both sides recognise.
+	*/
+	schemaVersion: z.number().int().nonnegative().default(1),
+	vaultNamespace: z.string().optional(),
+	secrets: z.array(TemplateSecretSchema).default([]),
+	requires: z.object({ airapp: z.boolean().optional() }).default({})
+});
+/**
+* `metadata.busabase` inside the root `SKILL.md`'s YAML frontmatter.
+*
+* `template: true` is an EXPLICIT opt-in, not an inference from "this skill
+* happens to contain a package". Publishing a template means accepting that
+* installers will run its AirApp code and feed its SKILL.md to their agent; that
+* deserves a deliberate flag rather than a side effect of directory shape.
+*/
+const SkillBusabaseMetadataSchema = z.object({
+	template: z.boolean().default(false),
+	folderSlug: z.string().optional(),
+	/** Resource keys the manual talks about; each must exist under `content/`. */
+	resources: z.array(z.string()).default([]),
+	risk: z.string().optional()
+});
+z.object({
+	name: z.string().min(1),
+	description: z.string().default(""),
+	metadata: z.object({ busabase: SkillBusabaseMetadataSchema.optional() }).passthrough().optional()
+});
+/** Stamp on every resource node (Base, Drive, AirApp, …) an app owns. */
+const AppResourceOwnershipSchema = z.object({
+	appId: z.string().min(1),
+	/** Stable internal handle (`"contacts"`), NOT the installed slug. */
+	resourceKey: z.string().min(1),
+	schemaVersion: z.number().int().nonnegative()
+});
+/**
+* The `resourceKey` reserved for an app's root Folder.
+*
+* `busabase-sdk` recognises an app's own Folder by looking for exactly this
+* value (`ownsAppRoot`), so the installer must write it too — a Folder stamped
+* with anything else reads as a stranger's, and the skill's own `setup.mjs`
+* then refuses to touch its own workspace with `SETUP_CONFLICT`. Exported so
+* neither side carries the string literal privately.
+*/
+const APP_ROOT_RESOURCE_KEY = "app-root";
+AppResourceOwnershipSchema.extend({
+	resourceKey: z.literal(APP_ROOT_RESOURCE_KEY),
+	version: z.string().optional(),
+	source: z.object({
+		repo: z.string().optional(),
+		ref: z.string().optional(),
+		subdir: z.string().optional()
+	}).optional(),
+	installedAt: z.string().optional()
+});
+z.object({
+	appId: z.string().min(1),
+	["isTemplateSkill"]: z.literal(true)
+});
+//#endregion
 //#region src/airapp.ts
 /**
+* AirApp resource provisioning — how an app claims (or creates) the Folder and
+* Bases it declares, exactly once, without ever taking over someone else's.
+*
+* Every App-in-Skill shipped a byte-identical copy of this module (280 lines ×
+* 65 apps, two spellings). That is the wrong place for it: the rules encoded
+* here are not app preferences, they are the safety boundary that keeps an app
+* from adopting a Folder a human created for something else. A third party
+* re-deriving them from scratch gets the happy path right and the conflict
+* cases wrong, and the failure is silent — the app happily writes into data it
+* does not own.
+*
+* The contract, in one line: **an app owns a node only if it stamped it.**
+* Ownership lives in `node.metadata` as `{ appId, resourceKey, schemaVersion }`.
+* Anything else is either a legacy node this app plausibly created before
+* stamping existed (claimable *only* after a full structural fingerprint match)
+* or someone else's (never touched, always a `SETUP_CONFLICT`).
+*
+* This module is isomorphic — browser and Node both — and holds no I/O beyond
+* the passed-in client.
+*
+* @example
+* ```ts
+* import { createBusabaseClient } from "busabase-sdk";
+* import { inspectProvisionedResources, provisionDeclaredResources } from "busabase-sdk/airapp";
+*
+* const client = createBusabaseClient({ baseUrl: window.location.origin });
+* const config = {
+*   appId: "kelly-crm",
+*   appName: "Kelly CRM",
+*   schemaVersion: 1,
+*   folder: { slug: "kelly-crm", name: "Kelly CRM", description: "CRM workspace" },
+*   bases: [{ key: "contacts", slug: "kelly-crm-contacts-v1", name: "Contacts", fields: [...] }],
+* };
+*
+* let resources = await inspectProvisionedResources(client, config);
+* if (!resources.folder || resources.missing.length) {
+*   resources = await provisionDeclaredResources(client, config); // one idempotent ChangeRequest
+* }
+* ```
+*/
+/**
 * A setup failure carrying its state as a `code`.
 *
 * `message` is deliberately kept in the historical `"CODE: detail"` shape: the
@@ -66,7 +216,7 @@ function resolveProvisionedFolder(folder, config) {
 		airApp: null
 	};
 	if (folder.node?.type !== "folder" || folder.node?.slug !== config.folder.slug) throw setupError("SETUP_CONFLICT", `A different Folder already uses the slug ${config.folder.slug}; nothing was changed`);
-	const rootOwned = hasResourceIdentity(folder.node, config.appId, "app-root");
+	const rootOwned = hasResourceIdentity(folder.node, config.appId, APP_ROOT_RESOURCE_KEY);
 	const legacyRoot = hasEmptyMetadata(folder.node) && matchesDeclaration(folder.node, config.folder, "folder");
 	if (!rootOwned && !legacyRoot) throw setupError("SETUP_CONFLICT", `The Folder ${config.folder.slug} does not belong to this app; nothing was changed`);
 	const bases = [];
@@ -74,8 +224,8 @@ function resolveProvisionedFolder(folder, config) {
 	const repairs = [];
 	if (!ownsAppRoot(folder.node, config.appId, config.schemaVersion)) repairs.push({
 		nodeId: folder.node.id,
-		resourceKey: "app-root",
-		metadata: resourceMetadata(config, "app-root")
+		resourceKey: APP_ROOT_RESOURCE_KEY,
+		metadata: resourceMetadata(config, APP_ROOT_RESOURCE_KEY)
 	});
 	for (const base of config.bases) {
 		const matches = (folder.children ?? []).filter((node) => node.slug === base.slug);
@@ -139,7 +289,7 @@ function buildProvisionOperations(config, folder, missingBases) {
 		slug: config.folder.slug,
 		name: config.folder.name,
 		description: config.folder.description ?? "",
-		metadata: resourceMetadata(config, "app-root")
+		metadata: resourceMetadata(config, APP_ROOT_RESOURCE_KEY)
 	});
 	for (const base of missingBases) operations.push({
 		kind: "create",

package/dist/{client-CbUceGzy.d.ts → client-slzL_ils.d.ts}

@@ -10635,6 +10635,7 @@ declare const cloudContract: {
         workspace: "workspace";
       }>>>;
       version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+      metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
       files: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         path: z.ZodString;
         assetId: z.ZodString;
@@ -13565,6 +13566,7 @@ declare const cloudContract: {
       }>;
       version: z.ZodDefault<z.ZodNullable<z.ZodString>>;
       available: z.ZodDefault<z.ZodBoolean>;
+      comingSoon: z.ZodDefault<z.ZodBoolean>;
       unavailableReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
       connectionRequired: z.ZodDefault<z.ZodBoolean>;
       connectedAgentName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -14336,6 +14338,41 @@ declare const cloudContract: {
       warnings: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
   };
+  templates: {
+    list: import("@orpc/contract").ContractProcedure<z.ZodDefault<z.ZodOptional<z.ZodObject<{
+      refresh: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>, z.ZodObject<{
+      templates: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        category: z.ZodString;
+        tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        screenshots: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        agentPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        version: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+        license: z.ZodOptional<z.ZodString>;
+        stats: z.ZodObject<{
+          folders: z.ZodNumber;
+          docs: z.ZodNumber;
+          bases: z.ZodNumber;
+          records: z.ZodNumber;
+          files: z.ZodNumber;
+          airapps: z.ZodNumber;
+          skill: z.ZodBoolean;
+        }, z.core.$strip>;
+        install: z.ZodObject<{
+          repoUrl: z.ZodString;
+          intoFolder: z.ZodString;
+        }, z.core.$strip>;
+        sourceUrl: z.ZodString;
+      }, z.core.$strip>>;
+      repo: z.ZodString;
+      ref: z.ZodString;
+      error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+  };
   changeRequests: {
     list: import("@orpc/contract").ContractProcedure<z.ZodDefault<z.ZodOptional<z.ZodObject<{
       limit: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { a as createBusabaseClient, c as cloudContract, d as NodeIconSchema, f as CREATABLE_NODE_TYPES, h as OperationKind, i as ResolvedConfig, l as NodeOutput, m as NodeType, n as BusabaseConfig, o as resolveConfig, p as CreatableNodeType, r as DEFAULT_BASE_URL, s as CloudContract, t as BusabaseClient, u as NodeIcon } from "./client-CbUceGzy.js";
+import { a as createBusabaseClient, c as cloudContract, d as NodeIconSchema, f as CREATABLE_NODE_TYPES, h as OperationKind, i as ResolvedConfig, l as NodeOutput, m as NodeType, n as BusabaseConfig, o as resolveConfig, p as CreatableNodeType, r as DEFAULT_BASE_URL, s as CloudContract, t as BusabaseClient, u as NodeIcon } from "./client-slzL_ils.js";
 import { z } from "zod";
 //#region src/url.d.ts
 /**

package/dist/index.js

@@ -86,6 +86,8 @@ const AgentCatalogEntryVOSchema = z.object({
 	version: z.string().nullable().default(null),
 	/** Whether this entry can be launched right now (binary present / URL configured). */
 	available: z.boolean().default(false),
+	/** Whether this integration is listed for discovery but not available yet. */
+	comingSoon: z.boolean().default(false),
 	/** Human-readable reason when `available` is false — never a bare "failed". */
 	unavailableReason: z.string().nullable().default(null),
 	connectionRequired: z.boolean().default(false),
@@ -1616,6 +1618,17 @@ const createFileTreeInputSchema = z.object({
 		"public"
 	]).optional().default("private"),
 	version: z.string().optional().default("0.1.0"),
+	/**
+	* Extra node metadata, stored alongside the server-owned keys.
+	*
+	* Rides along the change request on the review-first path, so it lands when a
+	* human merges. That is the whole point: an ownership stamp applied only
+	* after an immediate create would silently never be applied to a node that
+	* was proposed instead — leaving the app unable to recognise its own
+	* resources on the DEFAULT install path. Server-owned keys (`visibility`,
+	* `version`) always win, so a caller cannot use this to rewrite them.
+	*/
+	metadata: z.record(z.string(), z.unknown()).optional(),
 	files: z.array(z.union([assetFileInputSchema, textFileInputSchema])).optional().default([]),
 	autoMerge: z.boolean().optional(),
 	mergeMode: z.enum(["merge", "replace"]).optional().default("merge")
@@ -3146,6 +3159,92 @@ const installContract = {
 	}).input(InstallFromGithubDTOSchema).output(InstallResultVOSchema)
 };
 //#endregion
+//#region ../../packages/busabase-contract/src/domains/templates/types.ts
+/**
+* Template Center catalog types (pure zod, client-safe).
+*
+* The catalog is the file `busabase-cli index` builds from a skills repository
+* — see `busabase-package/index-build`. It is re-declared here rather than
+* imported because that module is Node-only (it reads packages), and these
+* shapes are rendered in a browser.
+*
+* Spec: `apps/busabase/content/spec/template-center.md` §6.4.
+*/
+const TemplateStatsVOSchema = z.object({
+	folders: z.number().int(),
+	docs: z.number().int(),
+	bases: z.number().int(),
+	records: z.number().int(),
+	files: z.number().int(),
+	airapps: z.number().int(),
+	skill: z.boolean()
+});
+const TemplateCardVOSchema = z.object({
+	/** Stable across a catalog: `<repo>/<subdir>`. What a route keys on. */
+	id: z.string(),
+	name: z.string(),
+	description: z.string(),
+	category: z.string(),
+	tags: z.array(z.string()).default([]),
+	/**
+	* Absolute URLs, resolved server-side.
+	*
+	* The catalog stores package-relative paths; turning them into URLs needs to
+	* know the repo and ref, which the server already has and the browser would
+	* otherwise have to re-derive. Doing it once here also means a card cannot
+	* accidentally point at a different ref than the one it installs.
+	*/
+	screenshots: z.array(z.string()).default([]),
+	agentPrompts: z.array(z.string()).default([]),
+	version: z.string().optional(),
+	author: z.string().optional(),
+	license: z.string().optional(),
+	stats: TemplateStatsVOSchema,
+	/** Exactly what the install dialog needs — no URL assembly in the client. */
+	install: z.object({
+		repoUrl: z.string(),
+		intoFolder: z.string()
+	}),
+	/** Where a curious user goes to read it before installing. */
+	sourceUrl: z.string()
+});
+const TemplateCatalogVOSchema = z.object({
+	templates: z.array(TemplateCardVOSchema),
+	/** `owner/repo` and ref the catalog was built from — shown as provenance. */
+	repo: z.string(),
+	ref: z.string(),
+	/**
+	* Why the catalog is empty or stale, in the server's own words.
+	*
+	* A gallery that silently shows nothing is indistinguishable from one that is
+	* broken, and the difference matters: "the catalog could not be fetched" is a
+	* thing a user can act on, "no templates" is not.
+	*/
+	error: z.string().optional()
+});
+const ListTemplatesDTOSchema = z.object({ 
+/** Bypass the cache — the refresh button. */
+refresh: z.boolean().optional() }).optional().default({});
+//#endregion
+//#region ../../packages/busabase-contract/src/domains/templates/contract.ts
+/**
+* Template Center — the catalog a user browses before installing.
+*
+* Read-only and server-side on purpose. The catalog lives in a GitHub
+* repository, and a browser fetching it directly would hit CORS, would have no
+* cache shared between users, and would let the page decide which host to trust.
+* Installing is NOT here: a card's button hands its URL to the existing
+* `install.*` routes, so browsing and installing cannot disagree about what a
+* package is or who is allowed to install it.
+*/
+const templatesContract = { list: oc.route({
+	method: "GET",
+	path: "/templates",
+	tags: ["Templates"],
+	summary: "List the Template Center catalog",
+	successDescription: "The templates this server's configured catalog publishes, with provenance and per-template stats. `error` is set when the catalog could not be fetched, so an empty gallery can say why."
+}).input(ListTemplatesDTOSchema).output(TemplateCatalogVOSchema) };
+//#endregion
 //#region ../../packages/busabase-contract/src/domains/vault/types.ts
 const VaultItemKeySchema = z.string().trim().min(1).max(128).regex(/^[A-Z_][A-Z0-9_]*$/, "Use uppercase letters, numbers, and underscores");
 const VaultItemValueSchema = z.string().max(8192);
@@ -4210,6 +4309,7 @@ const busabaseContractRoutes = {
 	webhooks: webhookContract,
 	dump: dumpContract,
 	install: installContract,
+	templates: templatesContract,
 	changeRequests: {
 		list: oc.route({
 			method: "GET",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busabase-sdk",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Typed TypeScript/JavaScript SDK for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server` (or Busabase Cloud).",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-sdk",
@@ -63,9 +63,9 @@
     "tsx": "^4.20.5",
     "typescript": "^7.0.2",
     "vitest": "^2.1.8",
-    "busabase-contract": "0.18.0",
-    "open-domains": "0.0.2",
-    "openlib": "0.1.1"
+    "busabase-contract": "0.19.0",
+    "openlib": "0.1.1",
+    "open-domains": "0.0.2"
   },
   "engines": {
     "node": ">=24.18.0"