@particle-academy/agent-integrations 0.20.0 → 0.21.1

package/dist/bridges/catalog.d.cts

@@ -0,0 +1,150 @@
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
+
+/**
+ * Headless bridge for `@particle-academy/fancy-catalog` — a Stripe catalog with
+ * NO UI surface. The adapter exposes the catalog's STORES + operations (not UI
+ * getters/setters), and the tools are CRUD over products / prices + checkout +
+ * Stripe sync. Mutations still funnel through `wrapToolWithActivity` so presence
+ * + undo compose, and the destructive delete is `pendingMode`-gated.
+ *
+ * The adapter shapes below are STRUCTURAL mirrors of fancy-catalog's public
+ * `Catalog` + store interfaces, defined LOCALLY so this bridge builds with the
+ * sibling package absent (it's an optional peer). A real `Catalog` instance is
+ * assignable to `CatalogBridgeAdapter` with no import — TypeScript is structural.
+ */
+/** Minimal product shape crossing the MCP wire (mirror of fancy-catalog `Product`). */
+type CatalogProduct = {
+    id: string;
+    name: string;
+    description?: string | null;
+    active?: boolean;
+    lookupKey?: string | null;
+    externalId?: string | null;
+    metadata?: Record<string, unknown> | null;
+    [k: string]: unknown;
+};
+/** Minimal price shape crossing the MCP wire (mirror of fancy-catalog `Price`). */
+type CatalogPrice = {
+    id: string;
+    productId: string;
+    active?: boolean;
+    currency: string;
+    unitAmount: number;
+    type: "recurring" | "one_time";
+    externalId?: string | null;
+    [k: string]: unknown;
+};
+/** Common checkout args (mirror of fancy-catalog `CheckoutArgs`). */
+type CatalogCheckoutArgs = {
+    customer?: string;
+    successUrl: string;
+    cancelUrl: string;
+    metadata?: Record<string, string>;
+    /** One-time checkouts only. */
+    quantity?: number;
+};
+/**
+ * Adapter = the catalog instance / stores. A live `Catalog` from fancy-catalog
+ * satisfies this directly (`catalog.products`, `catalog.createProduct`, …); a
+ * host can also hand-roll one over its own persistence.
+ */
+type CatalogBridgeAdapter = {
+    /** Stable id for this catalog instance (multiple catalogs ⇒ distinct ids). */
+    id?: string;
+    /** Display label for logs / presence. */
+    title?: string;
+    /** Optional fancy-screens screen id (usually unset — this is headless). */
+    screenId?: string;
+    /** Product store — `catalog.products`. */
+    products: {
+        find(id: string, opts?: {
+            withTrashed?: boolean;
+        }): CatalogProduct | null | Promise<CatalogProduct | null>;
+        all(opts?: {
+            withTrashed?: boolean;
+        }): CatalogProduct[] | Promise<CatalogProduct[]>;
+        remove(id: string): void | Promise<void>;
+    };
+    /** Price store — `catalog.prices`. */
+    prices: {
+        find(id: string, opts?: {
+            withTrashed?: boolean;
+        }): CatalogPrice | null | Promise<CatalogPrice | null>;
+        forProduct(productId: string, opts?: {
+            withTrashed?: boolean;
+        }): CatalogPrice[] | Promise<CatalogPrice[]>;
+        all(opts?: {
+            withTrashed?: boolean;
+        }): CatalogPrice[] | Promise<CatalogPrice[]>;
+        remove(id: string): void | Promise<void>;
+    };
+    /** Authoring helpers — `catalog.createProduct` / `catalog.createPrice` (ULIDs auto-assigned). */
+    createProduct(input: Partial<CatalogProduct> & {
+        name: string;
+    }): Promise<CatalogProduct> | CatalogProduct;
+    createPrice(input: Partial<CatalogPrice> & {
+        productId: string;
+        currency: string;
+        unitAmount: number;
+        type: "recurring" | "one_time";
+    }): Promise<CatalogPrice> | CatalogPrice;
+    /** Stripe sync — `catalog.syncProductAndPrices`. Optional (no-op when absent). */
+    syncProductAndPrices?(product: CatalogProduct): Promise<CatalogProduct> | CatalogProduct;
+    /** Connection test — `catalog.testConnection`. Optional. */
+    testConnection?(): Promise<{
+        success: boolean;
+        message: string;
+        productCount?: number;
+    }> | {
+        success: boolean;
+        message: string;
+        productCount?: number;
+    };
+    /** Hosted Checkout — `catalog.getSubscriptionCheckoutUrl` / `getOneTimeCheckoutUrl`. Optional. */
+    getSubscriptionCheckoutUrl?(price: CatalogPrice, args: CatalogCheckoutArgs): Promise<string> | string;
+    getOneTimeCheckoutUrl?(price: CatalogPrice, args: CatalogCheckoutArgs): Promise<string> | string;
+};
+type CatalogBridgeOptions = {
+    adapter: CatalogBridgeAdapter;
+    /** Identity stamped on activity + undo entries. */
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+    /**
+     * Trust-but-verify. When on (default), destructive ops (`catalog_delete_product`,
+     * `catalog_delete_price`) route through `adapter`-less staging: they require an
+     * explicit `confirm: true` arg OR a host `confirm` callback. Read + create +
+     * checkout-url tools are unaffected.
+     */
+    pendingMode?: boolean;
+    /** Host confirm hook for destructive ops (pendingMode). Resolves true to proceed. */
+    confirm?: (req: {
+        action: string;
+        id: string;
+        label: string;
+    }) => Promise<boolean> | boolean;
+};
+/**
+ * registerCatalogBridge — full MCP tool set over a headless Stripe catalog.
+ *
+ *   catalog_list_products    list products ({ id, name, active, priceCount })
+ *   catalog_get_product      full product JSON + its prices
+ *   catalog_create_product   create a product (ULID auto-assigned)
+ *   catalog_delete_product   soft-delete a product (pendingMode-gated, undoable*)
+ *   catalog_list_prices      list a product's prices (or all)
+ *   catalog_create_price     create a price under a product
+ *   catalog_delete_price     soft-delete a price (pendingMode-gated)
+ *   catalog_sync_product     push a product + its prices to Stripe
+ *   catalog_test_connection  verify the Stripe connection
+ *   catalog_create_checkout  build a hosted Checkout URL for a price
+ *
+ * *delete undo is best-effort: stores expose soft-delete (`remove`) but no
+ *  un-delete, so the undo closure re-creates from the captured snapshot.
+ */
+declare function registerCatalogBridge(host: ToolHost, options: CatalogBridgeOptions): Bridge;
+
+export { type CatalogBridgeAdapter, type CatalogBridgeOptions, type CatalogCheckoutArgs, type CatalogPrice, type CatalogProduct, registerCatalogBridge };

package/dist/bridges/catalog.d.ts

@@ -0,0 +1,150 @@
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
+
+/**
+ * Headless bridge for `@particle-academy/fancy-catalog` — a Stripe catalog with
+ * NO UI surface. The adapter exposes the catalog's STORES + operations (not UI
+ * getters/setters), and the tools are CRUD over products / prices + checkout +
+ * Stripe sync. Mutations still funnel through `wrapToolWithActivity` so presence
+ * + undo compose, and the destructive delete is `pendingMode`-gated.
+ *
+ * The adapter shapes below are STRUCTURAL mirrors of fancy-catalog's public
+ * `Catalog` + store interfaces, defined LOCALLY so this bridge builds with the
+ * sibling package absent (it's an optional peer). A real `Catalog` instance is
+ * assignable to `CatalogBridgeAdapter` with no import — TypeScript is structural.
+ */
+/** Minimal product shape crossing the MCP wire (mirror of fancy-catalog `Product`). */
+type CatalogProduct = {
+    id: string;
+    name: string;
+    description?: string | null;
+    active?: boolean;
+    lookupKey?: string | null;
+    externalId?: string | null;
+    metadata?: Record<string, unknown> | null;
+    [k: string]: unknown;
+};
+/** Minimal price shape crossing the MCP wire (mirror of fancy-catalog `Price`). */
+type CatalogPrice = {
+    id: string;
+    productId: string;
+    active?: boolean;
+    currency: string;
+    unitAmount: number;
+    type: "recurring" | "one_time";
+    externalId?: string | null;
+    [k: string]: unknown;
+};
+/** Common checkout args (mirror of fancy-catalog `CheckoutArgs`). */
+type CatalogCheckoutArgs = {
+    customer?: string;
+    successUrl: string;
+    cancelUrl: string;
+    metadata?: Record<string, string>;
+    /** One-time checkouts only. */
+    quantity?: number;
+};
+/**
+ * Adapter = the catalog instance / stores. A live `Catalog` from fancy-catalog
+ * satisfies this directly (`catalog.products`, `catalog.createProduct`, …); a
+ * host can also hand-roll one over its own persistence.
+ */
+type CatalogBridgeAdapter = {
+    /** Stable id for this catalog instance (multiple catalogs ⇒ distinct ids). */
+    id?: string;
+    /** Display label for logs / presence. */
+    title?: string;
+    /** Optional fancy-screens screen id (usually unset — this is headless). */
+    screenId?: string;
+    /** Product store — `catalog.products`. */
+    products: {
+        find(id: string, opts?: {
+            withTrashed?: boolean;
+        }): CatalogProduct | null | Promise<CatalogProduct | null>;
+        all(opts?: {
+            withTrashed?: boolean;
+        }): CatalogProduct[] | Promise<CatalogProduct[]>;
+        remove(id: string): void | Promise<void>;
+    };
+    /** Price store — `catalog.prices`. */
+    prices: {
+        find(id: string, opts?: {
+            withTrashed?: boolean;
+        }): CatalogPrice | null | Promise<CatalogPrice | null>;
+        forProduct(productId: string, opts?: {
+            withTrashed?: boolean;
+        }): CatalogPrice[] | Promise<CatalogPrice[]>;
+        all(opts?: {
+            withTrashed?: boolean;
+        }): CatalogPrice[] | Promise<CatalogPrice[]>;
+        remove(id: string): void | Promise<void>;
+    };
+    /** Authoring helpers — `catalog.createProduct` / `catalog.createPrice` (ULIDs auto-assigned). */
+    createProduct(input: Partial<CatalogProduct> & {
+        name: string;
+    }): Promise<CatalogProduct> | CatalogProduct;
+    createPrice(input: Partial<CatalogPrice> & {
+        productId: string;
+        currency: string;
+        unitAmount: number;
+        type: "recurring" | "one_time";
+    }): Promise<CatalogPrice> | CatalogPrice;
+    /** Stripe sync — `catalog.syncProductAndPrices`. Optional (no-op when absent). */
+    syncProductAndPrices?(product: CatalogProduct): Promise<CatalogProduct> | CatalogProduct;
+    /** Connection test — `catalog.testConnection`. Optional. */
+    testConnection?(): Promise<{
+        success: boolean;
+        message: string;
+        productCount?: number;
+    }> | {
+        success: boolean;
+        message: string;
+        productCount?: number;
+    };
+    /** Hosted Checkout — `catalog.getSubscriptionCheckoutUrl` / `getOneTimeCheckoutUrl`. Optional. */
+    getSubscriptionCheckoutUrl?(price: CatalogPrice, args: CatalogCheckoutArgs): Promise<string> | string;
+    getOneTimeCheckoutUrl?(price: CatalogPrice, args: CatalogCheckoutArgs): Promise<string> | string;
+};
+type CatalogBridgeOptions = {
+    adapter: CatalogBridgeAdapter;
+    /** Identity stamped on activity + undo entries. */
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+    /**
+     * Trust-but-verify. When on (default), destructive ops (`catalog_delete_product`,
+     * `catalog_delete_price`) route through `adapter`-less staging: they require an
+     * explicit `confirm: true` arg OR a host `confirm` callback. Read + create +
+     * checkout-url tools are unaffected.
+     */
+    pendingMode?: boolean;
+    /** Host confirm hook for destructive ops (pendingMode). Resolves true to proceed. */
+    confirm?: (req: {
+        action: string;
+        id: string;
+        label: string;
+    }) => Promise<boolean> | boolean;
+};
+/**
+ * registerCatalogBridge — full MCP tool set over a headless Stripe catalog.
+ *
+ *   catalog_list_products    list products ({ id, name, active, priceCount })
+ *   catalog_get_product      full product JSON + its prices
+ *   catalog_create_product   create a product (ULID auto-assigned)
+ *   catalog_delete_product   soft-delete a product (pendingMode-gated, undoable*)
+ *   catalog_list_prices      list a product's prices (or all)
+ *   catalog_create_price     create a price under a product
+ *   catalog_delete_price     soft-delete a price (pendingMode-gated)
+ *   catalog_sync_product     push a product + its prices to Stripe
+ *   catalog_test_connection  verify the Stripe connection
+ *   catalog_create_checkout  build a hosted Checkout URL for a price
+ *
+ * *delete undo is best-effort: stores expose soft-delete (`remove`) but no
+ *  un-delete, so the undo closure re-creates from the captured snapshot.
+ */
+declare function registerCatalogBridge(host: ToolHost, options: CatalogBridgeOptions): Bridge;
+
+export { type CatalogBridgeAdapter, type CatalogBridgeOptions, type CatalogCheckoutArgs, type CatalogPrice, type CatalogProduct, registerCatalogBridge };

package/dist/bridges/features.d.cts

@@ -0,0 +1,108 @@
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
+
+/**
+ * Headless bridge for `@particle-academy/fancy-features` — feature management
+ * with NO UI surface. The adapter is the `FeatureManager` (a `FeatureSource`
+ * consumer): define features in the registry, check access for a subject,
+ * grant/revoke via group assignment, and meter resource usage. Mutations
+ * funnel through `wrapToolWithActivity` so presence + undo compose; `grant` /
+ * `revoke` are `pendingMode`-gated (they change what a real user can do).
+ *
+ * The adapter shapes mirror fancy-features' public `FeatureManager` +
+ * `FeatureRegistry` + `GroupStore`, defined LOCALLY so the bridge builds with
+ * the sibling absent (optional peer). A live `FeatureManager` (plus its
+ * `.registry` / `.groupStore`) satisfies this structurally with no import.
+ *
+ * SUBJECTS over the wire: `Subject` is opaque (`unknown`) in fancy-features.
+ * Agents pass a JSON-serializable subject (string id or `{ id, … }` object);
+ * the host's stores key on it via their `defaultSubjectKey`.
+ */
+type FeatureGrant = {
+    key: string;
+    type: "boolean" | "resource";
+    enabled: boolean;
+    includedQuantity?: number | null;
+    overageLimit?: number | null;
+    source?: string;
+    config?: Record<string, unknown>;
+};
+/** Normalized feature definition (mirror of fancy-features `FeatureDefinition`). */
+type FeatureDefinition = {
+    key?: string;
+    name?: string;
+    description?: string;
+    type?: "boolean" | "resource";
+    enabled?: boolean;
+    limit?: number;
+    [k: string]: unknown;
+};
+/**
+ * Adapter = the `FeatureManager` + its registry + group store. The bridge only
+ * needs these members; a real manager exposes them directly.
+ */
+type FeaturesBridgeAdapter = {
+    /** Stable id for this feature manager instance. */
+    id?: string;
+    title?: string;
+    screenId?: string;
+    /** Can the subject access the feature now? `manager.canAccess`. */
+    canAccess(feature: string, subject?: unknown, context?: unknown): boolean | Promise<boolean>;
+    /** Remaining quota for a resource feature (null = unlimited / n-a). `manager.remaining`. */
+    remaining(feature: string, subject?: unknown, context?: unknown): number | null | Promise<number | null>;
+    /** All enabled feature keys for the subject. `manager.enabled`. */
+    enabled(subject?: unknown, context?: unknown): string[] | Promise<string[]>;
+    /** Trace a feature's resolution to an AccessResult. `manager.explain`. */
+    explain?(feature: string, subject?: unknown, context?: unknown): Promise<unknown> | unknown;
+    /** Register a programmatic feature. `manager.registerFeature` / `manager.registry.register`. */
+    registerFeature(key: string, definition: FeatureDefinition): void;
+    /** Registered feature keys. `manager.registry.keys`. */
+    registryKeys(): string[];
+    /** Resolve a registered definition (or null). `manager.registry.definition`. */
+    definition?(key: string): FeatureDefinition | null | Promise<FeatureDefinition | null>;
+    /** Assign a subject to a feature group (the grant primitive). `manager.groupStore.assign`. */
+    assignGroup(subject: unknown, groupKey: string): void | Promise<void>;
+    /** Detach a subject from a group (the revoke primitive). `manager.groupStore.detach`. */
+    detachGroup(subject: unknown, groupKey: string): void | Promise<void>;
+    /** Group keys assigned to a subject. `manager.groupStore.list`. */
+    listGroups(subject: unknown): string[] | Promise<string[]>;
+    /** Current usage for a resource feature. `manager.usageFor`. Optional. */
+    usageFor?(feature: string, subject: unknown): number | Promise<number>;
+    /** Atomic check-and-increment quota. `manager.tryConsume`. Optional. */
+    tryConsume?(feature: string, subject: unknown, amount?: number, context?: unknown): boolean | Promise<boolean>;
+};
+type FeaturesBridgeOptions = {
+    adapter: FeaturesBridgeAdapter;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+    /**
+     * Trust-but-verify. When on (default), `features_grant` / `features_revoke`
+     * (they change a real subject's entitlements) require `confirm:true` OR a
+     * host `confirm` hook. Checks + define + usage are unaffected.
+     */
+    pendingMode?: boolean;
+    confirm?: (req: {
+        action: string;
+        subject: unknown;
+        groupKey: string;
+    }) => Promise<boolean> | boolean;
+};
+/**
+ * registerFeaturesBridge — full MCP tool set over a headless feature manager.
+ *
+ *   features_list      enabled feature keys for a subject
+ *   features_check     can a subject access a feature? (+ remaining for resources)
+ *   features_explain   trace why a feature is on/off for a subject
+ *   features_define    register a feature definition (boolean / resource)
+ *   features_grant     assign a subject to a group (pendingMode-gated, undoable)
+ *   features_revoke    detach a subject from a group (pendingMode-gated, undoable)
+ *   features_groups    list a subject's assigned groups
+ *   features_consume   meter a resource feature (atomic check-and-increment)
+ */
+declare function registerFeaturesBridge(host: ToolHost, options: FeaturesBridgeOptions): Bridge;
+
+export { type FeatureDefinition, type FeatureGrant, type FeaturesBridgeAdapter, type FeaturesBridgeOptions, registerFeaturesBridge };

package/dist/bridges/features.d.ts

@@ -0,0 +1,108 @@
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
+
+/**
+ * Headless bridge for `@particle-academy/fancy-features` — feature management
+ * with NO UI surface. The adapter is the `FeatureManager` (a `FeatureSource`
+ * consumer): define features in the registry, check access for a subject,
+ * grant/revoke via group assignment, and meter resource usage. Mutations
+ * funnel through `wrapToolWithActivity` so presence + undo compose; `grant` /
+ * `revoke` are `pendingMode`-gated (they change what a real user can do).
+ *
+ * The adapter shapes mirror fancy-features' public `FeatureManager` +
+ * `FeatureRegistry` + `GroupStore`, defined LOCALLY so the bridge builds with
+ * the sibling absent (optional peer). A live `FeatureManager` (plus its
+ * `.registry` / `.groupStore`) satisfies this structurally with no import.
+ *
+ * SUBJECTS over the wire: `Subject` is opaque (`unknown`) in fancy-features.
+ * Agents pass a JSON-serializable subject (string id or `{ id, … }` object);
+ * the host's stores key on it via their `defaultSubjectKey`.
+ */
+type FeatureGrant = {
+    key: string;
+    type: "boolean" | "resource";
+    enabled: boolean;
+    includedQuantity?: number | null;
+    overageLimit?: number | null;
+    source?: string;
+    config?: Record<string, unknown>;
+};
+/** Normalized feature definition (mirror of fancy-features `FeatureDefinition`). */
+type FeatureDefinition = {
+    key?: string;
+    name?: string;
+    description?: string;
+    type?: "boolean" | "resource";
+    enabled?: boolean;
+    limit?: number;
+    [k: string]: unknown;
+};
+/**
+ * Adapter = the `FeatureManager` + its registry + group store. The bridge only
+ * needs these members; a real manager exposes them directly.
+ */
+type FeaturesBridgeAdapter = {
+    /** Stable id for this feature manager instance. */
+    id?: string;
+    title?: string;
+    screenId?: string;
+    /** Can the subject access the feature now? `manager.canAccess`. */
+    canAccess(feature: string, subject?: unknown, context?: unknown): boolean | Promise<boolean>;
+    /** Remaining quota for a resource feature (null = unlimited / n-a). `manager.remaining`. */
+    remaining(feature: string, subject?: unknown, context?: unknown): number | null | Promise<number | null>;
+    /** All enabled feature keys for the subject. `manager.enabled`. */
+    enabled(subject?: unknown, context?: unknown): string[] | Promise<string[]>;
+    /** Trace a feature's resolution to an AccessResult. `manager.explain`. */
+    explain?(feature: string, subject?: unknown, context?: unknown): Promise<unknown> | unknown;
+    /** Register a programmatic feature. `manager.registerFeature` / `manager.registry.register`. */
+    registerFeature(key: string, definition: FeatureDefinition): void;
+    /** Registered feature keys. `manager.registry.keys`. */
+    registryKeys(): string[];
+    /** Resolve a registered definition (or null). `manager.registry.definition`. */
+    definition?(key: string): FeatureDefinition | null | Promise<FeatureDefinition | null>;
+    /** Assign a subject to a feature group (the grant primitive). `manager.groupStore.assign`. */
+    assignGroup(subject: unknown, groupKey: string): void | Promise<void>;
+    /** Detach a subject from a group (the revoke primitive). `manager.groupStore.detach`. */
+    detachGroup(subject: unknown, groupKey: string): void | Promise<void>;
+    /** Group keys assigned to a subject. `manager.groupStore.list`. */
+    listGroups(subject: unknown): string[] | Promise<string[]>;
+    /** Current usage for a resource feature. `manager.usageFor`. Optional. */
+    usageFor?(feature: string, subject: unknown): number | Promise<number>;
+    /** Atomic check-and-increment quota. `manager.tryConsume`. Optional. */
+    tryConsume?(feature: string, subject: unknown, amount?: number, context?: unknown): boolean | Promise<boolean>;
+};
+type FeaturesBridgeOptions = {
+    adapter: FeaturesBridgeAdapter;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+    /**
+     * Trust-but-verify. When on (default), `features_grant` / `features_revoke`
+     * (they change a real subject's entitlements) require `confirm:true` OR a
+     * host `confirm` hook. Checks + define + usage are unaffected.
+     */
+    pendingMode?: boolean;
+    confirm?: (req: {
+        action: string;
+        subject: unknown;
+        groupKey: string;
+    }) => Promise<boolean> | boolean;
+};
+/**
+ * registerFeaturesBridge — full MCP tool set over a headless feature manager.
+ *
+ *   features_list      enabled feature keys for a subject
+ *   features_check     can a subject access a feature? (+ remaining for resources)
+ *   features_explain   trace why a feature is on/off for a subject
+ *   features_define    register a feature definition (boolean / resource)
+ *   features_grant     assign a subject to a group (pendingMode-gated, undoable)
+ *   features_revoke    detach a subject from a group (pendingMode-gated, undoable)
+ *   features_groups    list a subject's assigned groups
+ *   features_consume   meter a resource feature (atomic check-and-increment)
+ */
+declare function registerFeaturesBridge(host: ToolHost, options: FeaturesBridgeOptions): Bridge;
+
+export { type FeatureDefinition, type FeatureGrant, type FeaturesBridgeAdapter, type FeaturesBridgeOptions, registerFeaturesBridge };