@particle-academy/agent-integrations 0.20.0 → 0.21.1

package/dist/index.cjs

@@ -2431,6 +2431,521 @@ function registerNavigationBridge(host, options) {
   };
 }
 
+// src/bridges/catalog.ts
+var DEFAULT_AGENT10 = { id: "agent", name: "Agent", color: "#a855f7" };
+var str2 = (v, fallback = "") => typeof v === "string" ? v : fallback;
+var num2 = (v, fallback = 0) => typeof v === "number" && Number.isFinite(v) ? v : fallback;
+function registerCatalogBridge(host, options) {
+  const { adapter } = options;
+  const agent = { ...DEFAULT_AGENT10, ...options.agent ?? {} };
+  const pendingMode = options.pendingMode ?? true;
+  const catalogId = adapter.id ?? "catalog";
+  const disposers = [];
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
+  const target = (elementId, label) => ({
+    kind: "custom",
+    screenId: adapter.screenId,
+    elementId,
+    label: label ?? catalogId
+  });
+  const reg = (name, description, properties, required, handler, resolveTarget) => {
+    const wrapped = async (args) => {
+      try {
+        return await handler(args);
+      } catch (e) {
+        return errorResult(e instanceof Error ? e.message : String(e));
+      }
+    };
+    const final = resolveTarget ? wrapToolWithActivity(wrapped, {
+      toolName: name,
+      agent,
+      kind: "custom",
+      screenId: adapter.screenId,
+      resolveTarget: ({ args }) => resolveTarget(args)
+    }) : wrapped;
+    disposers.push(
+      host.registerTool(
+        { name, description, inputSchema: { type: "object", properties, required, additionalProperties: false } },
+        final
+      )
+    );
+  };
+  const guardDestructive = async (action, id, label, hasConfirmArg) => {
+    if (!pendingMode) return null;
+    if (options.confirm) {
+      const ok = await options.confirm({ action, id, label });
+      return ok ? null : errorResult(`Declined: ${action} ${id} (human did not confirm).`);
+    }
+    if (!hasConfirmArg) {
+      return errorResult(`${action} is staged (pendingMode). Re-call with confirm:true to apply, or wire a host confirm hook.`);
+    }
+    return null;
+  };
+  reg(
+    "catalog_list_products",
+    "List products: { id, name, active, lookupKey, priceCount }. Pass withTrashed:true to include soft-deleted.",
+    { withTrashed: { type: "boolean" } },
+    [],
+    async (args) => {
+      const products = await adapter.products.all({ withTrashed: args.withTrashed === true });
+      const list = await Promise.all(
+        products.map(async (p) => ({
+          id: p.id,
+          name: p.name,
+          active: p.active ?? true,
+          lookupKey: p.lookupKey ?? null,
+          priceCount: (await adapter.prices.forProduct(p.id)).length
+        }))
+      );
+      return textResult(JSON.stringify(list, null, 2), list);
+    },
+    false
+  );
+  reg(
+    "catalog_get_product",
+    "Read a product's full JSON plus its prices.",
+    { id: { type: "string" }, withTrashed: { type: "boolean" } },
+    ["id"],
+    async (args) => {
+      const id = str2(args.id);
+      const product = await adapter.products.find(id, { withTrashed: args.withTrashed === true });
+      if (!product) return errorResult(`No product with id ${id}`);
+      const prices = await adapter.prices.forProduct(id, { withTrashed: args.withTrashed === true });
+      const out = { product, prices };
+      return textResult(JSON.stringify(out, null, 2), out);
+    },
+    false
+  );
+  reg(
+    "catalog_list_prices",
+    "List prices for a product (pass productId), or every price (omit it).",
+    { productId: { type: "string" }, withTrashed: { type: "boolean" } },
+    [],
+    async (args) => {
+      const withTrashed = args.withTrashed === true;
+      const prices = args.productId !== void 0 ? await adapter.prices.forProduct(str2(args.productId), { withTrashed }) : await adapter.prices.all({ withTrashed });
+      const list = prices.map((p) => ({
+        id: p.id,
+        productId: p.productId,
+        currency: p.currency,
+        unitAmount: p.unitAmount,
+        type: p.type,
+        active: p.active ?? true,
+        externalId: p.externalId ?? null
+      }));
+      return textResult(JSON.stringify(list, null, 2), list);
+    },
+    false
+  );
+  reg(
+    "catalog_create_product",
+    "Create a product. `name` is required; id (ULID) is auto-assigned. Returns the created product.",
+    {
+      name: { type: "string" },
+      description: { type: "string" },
+      active: { type: "boolean" },
+      lookupKey: { type: "string" },
+      metadata: { type: "object" }
+    },
+    ["name"],
+    async (args) => {
+      const name = str2(args.name);
+      if (!name) return errorResult("name is required.");
+      const product = await adapter.createProduct({
+        name,
+        ...args.description !== void 0 ? { description: str2(args.description) } : {},
+        ...args.active !== void 0 ? { active: args.active === true } : {},
+        ...args.lookupKey !== void 0 ? { lookupKey: str2(args.lookupKey) } : {},
+        ...args.metadata && typeof args.metadata === "object" ? { metadata: args.metadata } : {}
+      });
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: catalogId,
+        action: "catalog_create_product",
+        label: `Created product ${product.id} (${product.name})`,
+        undo: () => void adapter.products.remove(product.id),
+        redo: () => void adapter.createProduct({ ...product })
+      });
+      return textResult(`Created product ${product.id} (${product.name})`, product);
+    },
+    (args) => target(void 0, `create product ${str2(args.name)}`)
+  );
+  reg(
+    "catalog_create_price",
+    "Create a price under a product. unitAmount is integer minor units (cents). type is 'recurring' | 'one_time'.",
+    {
+      productId: { type: "string" },
+      currency: { type: "string", description: "ISO-4217, e.g. 'USD'." },
+      unitAmount: { type: "number", description: "Price in cents." },
+      type: { type: "string", enum: ["recurring", "one_time"] },
+      recurringInterval: { type: "string", description: "'month' | 'year' | \u2026 (recurring only)." },
+      nickname: { type: "string" },
+      lookupKey: { type: "string" },
+      metadata: { type: "object" }
+    },
+    ["productId", "currency", "unitAmount", "type"],
+    async (args) => {
+      const productId = str2(args.productId);
+      const product = await adapter.products.find(productId);
+      if (!product) return errorResult(`No product with id ${productId}`);
+      const type = str2(args.type);
+      if (type !== "recurring" && type !== "one_time") return errorResult("type must be 'recurring' or 'one_time'.");
+      const price = await adapter.createPrice({
+        productId,
+        currency: str2(args.currency),
+        unitAmount: num2(args.unitAmount),
+        type,
+        ...args.recurringInterval !== void 0 ? { recurringInterval: str2(args.recurringInterval) } : {},
+        ...args.nickname !== void 0 ? { nickname: str2(args.nickname) } : {},
+        ...args.lookupKey !== void 0 ? { lookupKey: str2(args.lookupKey) } : {},
+        ...args.metadata && typeof args.metadata === "object" ? { metadata: args.metadata } : {}
+      });
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: catalogId,
+        action: "catalog_create_price",
+        label: `Created price ${price.id} on ${productId}`,
+        undo: () => void adapter.prices.remove(price.id),
+        redo: () => void adapter.createPrice({ ...price })
+      });
+      return textResult(`Created ${type} price ${price.id} on ${productId}`, price);
+    },
+    (args) => target(str2(args.productId), `create price on ${str2(args.productId)}`)
+  );
+  reg(
+    "catalog_delete_product",
+    "Soft-delete a product (preserves financial history). Staged in pendingMode \u2014 pass confirm:true or wire a host confirm hook.",
+    { id: { type: "string" }, confirm: { type: "boolean" } },
+    ["id"],
+    async (args) => {
+      const id = str2(args.id);
+      const product = await adapter.products.find(id, { withTrashed: true });
+      if (!product) return errorResult(`No product with id ${id}`);
+      const blocked = await guardDestructive("catalog_delete_product", id, product.name, args.confirm === true);
+      if (blocked) return blocked;
+      const snapshot = { ...product };
+      await adapter.products.remove(id);
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: catalogId,
+        action: "catalog_delete_product",
+        label: `Deleted product ${id} (${product.name})`,
+        undo: () => void adapter.createProduct({ ...snapshot }),
+        redo: () => void adapter.products.remove(id)
+      });
+      return textResult(`Deleted product ${id}`, { id });
+    },
+    (args) => target(str2(args.id), `delete product ${str2(args.id)}`)
+  );
+  reg(
+    "catalog_delete_price",
+    "Soft-delete a price (mirrors Stripe archiving). Staged in pendingMode \u2014 pass confirm:true or wire a host confirm hook.",
+    { id: { type: "string" }, confirm: { type: "boolean" } },
+    ["id"],
+    async (args) => {
+      const id = str2(args.id);
+      const price = await adapter.prices.find(id, { withTrashed: true });
+      if (!price) return errorResult(`No price with id ${id}`);
+      const blocked = await guardDestructive("catalog_delete_price", id, id, args.confirm === true);
+      if (blocked) return blocked;
+      const snapshot = { ...price };
+      await adapter.prices.remove(id);
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: catalogId,
+        action: "catalog_delete_price",
+        label: `Deleted price ${id}`,
+        undo: () => void adapter.createPrice({ ...snapshot }),
+        redo: () => void adapter.prices.remove(id)
+      });
+      return textResult(`Deleted price ${id}`, { id });
+    },
+    (args) => target(str2(args.id), `delete price ${str2(args.id)}`)
+  );
+  reg(
+    "catalog_sync_product",
+    "Push a product + its prices to Stripe (creates/updates the Stripe Product + Prices, stamps external ids).",
+    { id: { type: "string" } },
+    ["id"],
+    async (args) => {
+      if (!adapter.syncProductAndPrices) return errorResult("Host did not wire Stripe sync.");
+      const id = str2(args.id);
+      const product = await adapter.products.find(id);
+      if (!product) return errorResult(`No product with id ${id}`);
+      const synced = await adapter.syncProductAndPrices(product);
+      return textResult(`Synced product ${id} to Stripe (${synced.externalId ?? "no external id"})`, synced);
+    },
+    (args) => target(str2(args.id), `sync product ${str2(args.id)}`)
+  );
+  reg(
+    "catalog_test_connection",
+    "Verify the Stripe connection \u2014 returns { success, message, productCount? }.",
+    {},
+    [],
+    async () => {
+      if (!adapter.testConnection) return errorResult("Host did not wire a Stripe connection test.");
+      const result = await adapter.testConnection();
+      return textResult(JSON.stringify(result, null, 2), result);
+    },
+    false
+  );
+  reg(
+    "catalog_create_checkout",
+    "Build a hosted Stripe Checkout URL for a price. Recurring prices \u2192 subscription; one-time \u2192 payment (pass quantity). Requires the price be synced to Stripe first.",
+    {
+      priceId: { type: "string" },
+      successUrl: { type: "string" },
+      cancelUrl: { type: "string" },
+      customer: { type: "string", description: "Stripe customer id (optional \u2014 Checkout collects one if omitted)." },
+      quantity: { type: "number", description: "One-time checkouts only. Default 1." },
+      metadata: { type: "object" }
+    },
+    ["priceId", "successUrl", "cancelUrl"],
+    async (args) => {
+      const priceId = str2(args.priceId);
+      const price = await adapter.prices.find(priceId);
+      if (!price) return errorResult(`No price with id ${priceId}`);
+      const checkoutArgs = {
+        successUrl: str2(args.successUrl),
+        cancelUrl: str2(args.cancelUrl),
+        ...args.customer !== void 0 ? { customer: str2(args.customer) } : {},
+        ...args.metadata && typeof args.metadata === "object" ? { metadata: args.metadata } : {}
+      };
+      let url;
+      if (price.type === "recurring") {
+        if (!adapter.getSubscriptionCheckoutUrl) return errorResult("Host did not wire subscription checkout.");
+        url = await adapter.getSubscriptionCheckoutUrl(price, checkoutArgs);
+      } else {
+        if (!adapter.getOneTimeCheckoutUrl) return errorResult("Host did not wire one-time checkout.");
+        url = await adapter.getOneTimeCheckoutUrl(price, { ...checkoutArgs, quantity: num2(args.quantity, 1) });
+      }
+      return textResult(url || "(no url)", { priceId, type: price.type, url });
+    },
+    (args) => target(str2(args.priceId), `checkout ${str2(args.priceId)}`)
+  );
+  return {
+    id: `catalog:${catalogId}`,
+    title: adapter.title ?? "Catalog",
+    dispose: () => {
+      for (const d of disposers.splice(0)) d();
+    }
+  };
+}
+
+// src/bridges/features.ts
+var DEFAULT_AGENT11 = { id: "agent", name: "Agent", color: "#a855f7" };
+var str3 = (v, fallback = "") => typeof v === "string" ? v : fallback;
+var num3 = (v, fallback = 0) => typeof v === "number" && Number.isFinite(v) ? v : fallback;
+function registerFeaturesBridge(host, options) {
+  const { adapter } = options;
+  const agent = { ...DEFAULT_AGENT11, ...options.agent ?? {} };
+  const pendingMode = options.pendingMode ?? true;
+  const featuresId = adapter.id ?? "features";
+  const disposers = [];
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
+  const target = (elementId, label) => ({
+    kind: "custom",
+    screenId: adapter.screenId,
+    elementId,
+    label: label ?? featuresId
+  });
+  const reg = (name, description, properties, required, handler, resolveTarget) => {
+    const wrapped = async (args) => {
+      try {
+        return await handler(args);
+      } catch (e) {
+        return errorResult(e instanceof Error ? e.message : String(e));
+      }
+    };
+    const final = resolveTarget ? wrapToolWithActivity(wrapped, {
+      toolName: name,
+      agent,
+      kind: "custom",
+      screenId: adapter.screenId,
+      resolveTarget: ({ args }) => resolveTarget(args)
+    }) : wrapped;
+    disposers.push(
+      host.registerTool(
+        { name, description, inputSchema: { type: "object", properties, required, additionalProperties: false } },
+        final
+      )
+    );
+  };
+  const guardGrant = async (action, subject, groupKey, hasConfirmArg) => {
+    if (!pendingMode) return null;
+    if (options.confirm) {
+      const ok = await options.confirm({ action, subject, groupKey });
+      return ok ? null : errorResult(`Declined: ${action} ${groupKey} (human did not confirm).`);
+    }
+    if (!hasConfirmArg) {
+      return errorResult(`${action} is staged (pendingMode). Re-call with confirm:true to apply, or wire a host confirm hook.`);
+    }
+    return null;
+  };
+  reg(
+    "features_list",
+    "List the feature keys enabled for a subject. Pass `subject` (a string id or object).",
+    { subject: { description: "Opaque subject \u2014 string id or { id, \u2026 } object." }, context: { description: "Optional resolution context." } },
+    [],
+    async (args) => {
+      const keys = await adapter.enabled(args.subject, args.context);
+      return textResult(JSON.stringify(keys, null, 2), { subject: args.subject, enabled: keys });
+    },
+    false
+  );
+  reg(
+    "features_check",
+    "Check whether a subject can access a feature. For resource features also returns the remaining quota.",
+    { feature: { type: "string" }, subject: { description: "Opaque subject." }, context: { description: "Optional context." } },
+    ["feature"],
+    async (args) => {
+      const feature = str3(args.feature);
+      const allowed = await adapter.canAccess(feature, args.subject, args.context);
+      const remaining = await adapter.remaining(feature, args.subject, args.context);
+      const out = { feature, allowed, remaining };
+      return textResult(JSON.stringify(out), out);
+    },
+    false
+  );
+  reg(
+    "features_explain",
+    "Trace why a feature is on/off for a subject \u2014 returns the AccessResult (source, remaining, limit, used).",
+    { feature: { type: "string" }, subject: { description: "Opaque subject." }, context: { description: "Optional context." } },
+    ["feature"],
+    async (args) => {
+      if (!adapter.explain) return errorResult("Host did not wire explain().");
+      const result = await adapter.explain(str3(args.feature), args.subject, args.context);
+      return textResult(JSON.stringify(result, null, 2), result);
+    },
+    false
+  );
+  reg(
+    "features_groups",
+    "List the feature groups a subject is assigned to.",
+    { subject: { description: "Opaque subject." } },
+    ["subject"],
+    async (args) => {
+      const groups = await adapter.listGroups(args.subject);
+      return textResult(JSON.stringify(groups, null, 2), { subject: args.subject, groups });
+    },
+    false
+  );
+  reg(
+    "features_define",
+    "Register a feature definition. type 'boolean' (on/off) or 'resource' (metered with a `limit`). `enabled` sets the default gate.",
+    {
+      key: { type: "string" },
+      name: { type: "string" },
+      description: { type: "string" },
+      type: { type: "string", enum: ["boolean", "resource"] },
+      enabled: { type: "boolean" },
+      limit: { type: "number", description: "Resource quota per period (resource type)." }
+    },
+    ["key"],
+    (args) => {
+      const key = str3(args.key);
+      if (!key) return errorResult("key is required.");
+      const existed = adapter.registryKeys().includes(key);
+      const definition = {
+        ...args.name !== void 0 ? { name: str3(args.name) } : {},
+        ...args.description !== void 0 ? { description: str3(args.description) } : {},
+        ...args.type !== void 0 ? { type: str3(args.type) } : {},
+        ...args.enabled !== void 0 ? { enabled: args.enabled === true } : {},
+        ...args.limit !== void 0 ? { limit: num3(args.limit) } : {}
+      };
+      adapter.registerFeature(key, definition);
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: featuresId,
+        action: "features_define",
+        // Registry has no unregister; undo re-registers the prior definition when we had one.
+        label: existed ? `Redefined feature ${key}` : `Defined feature ${key}`,
+        undo: () => {
+        },
+        redo: () => adapter.registerFeature(key, definition)
+      });
+      return textResult(`${existed ? "Redefined" : "Defined"} feature ${key} (${definition.type ?? "boolean"})`, { key, definition });
+    },
+    (args) => target(str3(args.key), `define ${str3(args.key)}`)
+  );
+  reg(
+    "features_grant",
+    "Grant a subject access by assigning it to a feature group. Staged in pendingMode \u2014 pass confirm:true or wire a host confirm hook.",
+    { subject: { description: "Opaque subject." }, group: { type: "string", description: "Feature group key." }, confirm: { type: "boolean" } },
+    ["subject", "group"],
+    async (args) => {
+      const groupKey = str3(args.group);
+      if (!groupKey) return errorResult("group is required.");
+      const blocked = await guardGrant("features_grant", args.subject, groupKey, args.confirm === true);
+      if (blocked) return blocked;
+      const already = (await adapter.listGroups(args.subject)).includes(groupKey);
+      await adapter.assignGroup(args.subject, groupKey);
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: featuresId,
+        action: "features_grant",
+        label: `Granted group ${groupKey}`,
+        // Only reverse if WE added it (idempotent assign — don't revoke a pre-existing grant).
+        undo: () => {
+          if (!already) void adapter.detachGroup(args.subject, groupKey);
+        },
+        redo: () => void adapter.assignGroup(args.subject, groupKey)
+      });
+      return textResult(`Granted group ${groupKey}`, { subject: args.subject, group: groupKey });
+    },
+    (args) => target(str3(args.group), `grant ${str3(args.group)}`)
+  );
+  reg(
+    "features_revoke",
+    "Revoke access by detaching a subject from a feature group. Staged in pendingMode \u2014 pass confirm:true or wire a host confirm hook.",
+    { subject: { description: "Opaque subject." }, group: { type: "string" }, confirm: { type: "boolean" } },
+    ["subject", "group"],
+    async (args) => {
+      const groupKey = str3(args.group);
+      if (!groupKey) return errorResult("group is required.");
+      const blocked = await guardGrant("features_revoke", args.subject, groupKey, args.confirm === true);
+      if (blocked) return blocked;
+      const had = (await adapter.listGroups(args.subject)).includes(groupKey);
+      await adapter.detachGroup(args.subject, groupKey);
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: featuresId,
+        action: "features_revoke",
+        label: `Revoked group ${groupKey}`,
+        undo: () => {
+          if (had) void adapter.assignGroup(args.subject, groupKey);
+        },
+        redo: () => void adapter.detachGroup(args.subject, groupKey)
+      });
+      return textResult(`Revoked group ${groupKey}`, { subject: args.subject, group: groupKey });
+    },
+    (args) => target(str3(args.group), `revoke ${str3(args.group)}`)
+  );
+  reg(
+    "features_consume",
+    "Meter a resource feature: atomic check-and-increment. Returns ok:false if the quota would be exceeded (nothing recorded).",
+    { feature: { type: "string" }, subject: { description: "Opaque subject." }, amount: { type: "number", description: "Units to consume. Default 1." }, context: { description: "Optional context." } },
+    ["feature", "subject"],
+    async (args) => {
+      if (!adapter.tryConsume) return errorResult("Host did not wire usage metering (tryConsume).");
+      const feature = str3(args.feature);
+      const amount = num3(args.amount, 1);
+      const ok = await adapter.tryConsume(feature, args.subject, amount, args.context);
+      const remaining = await adapter.remaining(feature, args.subject, args.context);
+      const out = { feature, ok, amount, remaining };
+      return textResult(JSON.stringify(out), out);
+    },
+    (args) => target(str3(args.feature), `consume ${str3(args.feature)}`)
+  );
+  return {
+    id: `features:${featuresId}`,
+    title: adapter.title ?? "Features",
+    dispose: () => {
+      for (const d of disposers.splice(0)) d();
+    }
+  };
+}
+
 // src/sharing/token.ts
 var TOKEN_BYTES = 24;
 function createSessionDescriptor() {
@@ -2625,11 +3140,11 @@ function attachSseRelay(server, options) {
 
 // src/sharing/use-co-browse-session.ts
 init_registry();
-var DEFAULT_AGENT10 = { id: "agent", name: "Agent", color: "#a855f7" };
+var DEFAULT_AGENT12 = { id: "agent", name: "Agent", color: "#a855f7" };
 var USER = { id: "human", name: "You" };
 function useCoBrowseSession(options) {
   const { adapter, extraBridges } = options;
-  const agent = { ...DEFAULT_AGENT10, ...options.agent ?? {} };
+  const agent = { ...DEFAULT_AGENT12, ...options.agent ?? {} };
   const relayBaseUrl = options.relayBaseUrl ?? "/agent-relay";
   const serverRef = react.useRef(null);
   const relayRef = react.useRef(null);
@@ -3175,7 +3690,7 @@ function buildVscodeDeeplink(server, opts = {}) {
   return `${scheme}://mcp/install?${payload}`;
 }
 function slugifyServerName(name) {
-  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
   return slug || "mcp-server";
 }
 function buildManualConfig(server) {
@@ -3851,8 +4366,10 @@ exports.ensureUndoToolsRegistered = ensureUndoToolsRegistered;
 exports.errorResult = errorResult;
 exports.mapActivityToHeuristicsEvent = mapActivityToEvent;
 exports.readSessionFromUrl = readSessionFromUrl;
+exports.registerCatalogBridge = registerCatalogBridge;
 exports.registerChartsBridge = registerChartsBridge;
 exports.registerCodeBridge = registerCodeBridge;
+exports.registerFeaturesBridge = registerFeaturesBridge;
 exports.registerFormBridge = registerFormBridge;
 exports.registerNavigationBridge = registerNavigationBridge;
 exports.registerSceneBridge = registerSceneBridge;