@vertesia/common 1.0.0-dev.20260203.130115Z → 1.0.0-dev.20260227.104700Z

package/lib/types/apps.d.ts

@@ -0,0 +1,481 @@
+import { JSONSchema, ToolDefinition } from "@llumiverse/common";
+import { CatalogInteractionRef } from "./interaction.js";
+import { InCodeTypeDefinition } from "./store/index.js";
+/**
+ * Additional navigation item for an app's UI configuration.
+ * Used in AppUIConfig.navigation to define sidebar navigation entries in CompositeApp shell contexts.
+ * Icon values are Lucide icon component names or SVG content strings.
+ */
+export interface AppUINavItem {
+    /** Display label */
+    label: string;
+    /** Lucide icon name or SVG content string */
+    icon: string;
+    /** Route path relative to app base */
+    route: string;
+}
+export interface AppUIConfig {
+    /**
+     * The source URL of the app. The src can be a template which contain
+     * a variable named `buildId` which will be replaced with the current build id.
+     * For example: `/plugins/vertesia-review-center-${buildId}`
+     */
+    src: string;
+    /**
+     * The isolation strategy. If not specified it defaults to shadow
+     * - shadow - use Shadow DOM to fully isolate the plugin from the host.
+     * - css - use CSS processing (like prefixing or other isolation techniques). Ligther but plugins may conflict with the host
+     */
+    isolation?: "shadow" | "css";
+    /**
+     * Navigation items for the app's sidebar UI.
+     * Only applicable for apps with UI capability in shell contexts (ie. CompositeApp shell).
+     */
+    navigation?: AppUINavItem[];
+    /**
+     * Where this app's UI can be displayed.
+     * - 'app_portal': Available in the main app portal (standalone)
+     * - 'composite_app': Available within a CompositeApp shell
+     * Defaults to ['app_portal', 'composite_app'] for new apps.
+     */
+    available_in?: AppAvailableIn[];
+}
+/**
+ * Authentication type for tool collections
+ */
+export type ToolCollectionAuthType = "oauth" | "other";
+/**
+ * Tool collection type
+ */
+export type ToolCollectionType = "mcp" | "vertesia_sdk";
+/**
+ * Base tool collection configuration
+ */
+interface BaseToolCollectionObject {
+    /**
+     * The URL endpoint for the tool collection
+     */
+    url: string;
+    /**
+     * Optional authentication type required for this tool collection
+     */
+    auth?: ToolCollectionAuthType;
+}
+/**
+ * MCP tool collection configuration (requires name, description, and namespace)
+ */
+export interface MCPToolCollectionObject extends BaseToolCollectionObject {
+    type: "mcp";
+    /**
+     * Name for the tool collection.
+     * Used as an identifier for the collection (e.g., for OAuth authentication).
+     */
+    name: string;
+    /**
+     * Description for the tool collection.
+     * Helps users understand what tools this collection provides.
+     */
+    description: string;
+    /**
+     * Prefix to use for tool names from this collection.
+     * Provides clean, readable tool names (e.g., "jira" instead of "https://mcp.atlassian.com/v1/mcp")
+     */
+    namespace: string;
+}
+/**
+ * Vertesia SDK tool collection configuration
+ */
+export interface VertesiaSDKToolCollectionObject extends BaseToolCollectionObject {
+    type: "vertesia_sdk";
+    /**
+     * Optional namespace to use for tool names from this collection.
+     * If not provided, the tool server default will be used.
+     */
+    namespace?: string;
+    /**
+     * Optional name for the tool collection.
+     * If not provided, the tool server default will be used.
+     */
+    name?: string;
+    /**
+     * Optional description for the tool collection.
+     * If not provided, the tool server default will be used.
+     */
+    description?: string;
+}
+/**
+ * Tool collection configuration (object format)
+ */
+export type ToolCollectionObject = MCPToolCollectionObject | VertesiaSDKToolCollectionObject;
+/**
+ * Tool collection can be either:
+ * - A string URL (legacy format, with "mcp:" prefix for MCP servers)
+ * - An object with url, type, and optional auth (new format)
+ */
+export type ToolCollection = string | ToolCollectionObject;
+/**
+ * Normalizes a tool collection to the object format.
+ * Handles backward compatibility with string URLs.
+ *
+ * @param collection - String URL or ToolCollectionObject
+ * @returns Normalized ToolCollectionObject
+ */
+export declare function normalizeToolCollection(collection: ToolCollection): ToolCollectionObject;
+/**
+ * Tool definition with optional activation control for agent exposure.
+ */
+export interface AgentToolDefinition extends ToolDefinition {
+    /**
+     * The tool execution URL. It can be an absolute URL or a path in which case the URL is obtained
+     * using the base URL of the tool server API. Ex: http://tool-server.com/api/
+     * Example of relative URLs: "tools/my-tool-collection" or "/api/tools/my-tool-collection"
+     */
+    url?: string;
+    /**
+     * The tool category if any - for UI purposes.
+     */
+    category?: string;
+    /**
+     * Whether this tool is available by default.
+     * - true/undefined: Tool is always available to agents
+     * - false: Tool is only available when activated by a skill's related_tools
+     */
+    default?: boolean;
+    /**
+     * For skill tools (learn_*): list of related tool names that become available
+     * when this skill is called. Used for dynamic tool discovery.
+     */
+    related_tools?: string[];
+}
+export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types' | 'templates';
+export type AppAvailableIn = 'app_portal' | 'composite_app';
+export interface AppManifestData {
+    /**
+     * The name of the app, used as the id in the system.
+     * Must be in kebab case (e.g. my-app).
+     */
+    name: string;
+    /**
+     * Visibility level of the app:
+     * - "public": visible to all accounts
+     * - "private": visible only to the owning account
+     * - "vertesia": visible only to Vertesia team members (any project)
+     */
+    visibility: "public" | "private" | "vertesia";
+    title: string;
+    description: string;
+    publisher: string;
+    /**
+     * A svg icon for the app.
+     */
+    icon?: string;
+    /**
+     * A color name to be used as the color of the app card (e.g. blue, red, green, etc.)
+     * If not specified a random color will be picked.
+     */
+    color?: string;
+    status: "beta" | "stable" | "deprecated";
+    /**
+     * The UI configuration of the app. If not specified and the app "ui" is in the app capabilities
+     * then the ui configuration will be fetched from the endpoint property.
+     */
+    ui?: AppUIConfig;
+    /**
+     * A list of tool collections endpoints to be used by this app.
+     * A tools collection endpoint is an URL which may end with a `?import` query string.
+     * If the `?import` query string is used the tool will be imported as a javascript module and not executed through a POST on the collections endpoint.
+     * This feature is for advanced composition of tools. Prefer using endpoint.
+     */
+    tool_collections?: ToolCollection[];
+    /**
+     * An URL providing interactions definitions in JSON format.
+     * The URL must provide 2 endpoints:
+     * 1. GET URL - must return a JSON array with the list of interactions (as AppInteractionRef[])
+     * 2. GET URL/{interaction_name} - must return the full interaction definition for the specified interaction.
+     * This feature is for advanced composition of interactions. Prefer using endpoint.
+     */
+    interactions?: string;
+    /**
+     * A JSON chema for the app installation settings.
+     * @deprecated Use endpoint to provide settings_schema instead
+     */
+    settings_schema?: JSONSchema;
+    /** The following API is part of the second version of the manifest and deprectaes similar properties included directly in the manifest */
+    /**
+     * Describe the capabiltities of this app - which kind of contributions it provides.
+     */
+    capabilities?: AppCapabilities[];
+    /**
+     * The app endpoint URL
+     * This URL should return a JSON object describing the contributions provided by the app.
+     * The object shape must satisfies AppPackage interface.
+     * The endpoint must support GET method and a `scope` parameter to filter which resources are included in the returned AppPackage:
+     * The supported scope values are:
+     * - ui
+     * - tools
+     * - interactions
+     * - types
+     * - settings
+     * - all (the default if no scope is provided)
+     *  You can also use comma-separated values to combine scopes (e.g. "ui,tools").
+     *
+     * Example:
+     * - ?scope=ui,tools - returns only the UI configuration
+     */
+    endpoint?: string;
+}
+export type AppPackageScope = 'ui' | 'tools' | 'interactions' | 'types' | 'templates' | 'settings' | 'widgets' | 'all';
+export interface AppPackage {
+    /**
+     * The UI configuration of the app
+     */
+    ui?: AppUIConfig;
+    /**
+     * A list of tools exposed by the app.
+     */
+    tools?: AgentToolDefinition[];
+    /**
+     * A list of interactions exposed by the app
+     */
+    interactions?: CatalogInteractionRef[];
+    /**
+     * A list of types.
+     */
+    types?: InCodeTypeDefinition[];
+    /**
+     * Templates provided by the app.
+     */
+    templates?: RenderingTemplateDefinitionRef[];
+    /**
+     * Widgets provided by the app.
+     */
+    widgets?: Record<string, AppWidgetInfo>;
+    /**
+     * A JSON chema for the app installation settings.
+     */
+    settings_schema?: JSONSchema;
+}
+export interface AppWidgetInfo {
+    collection: string;
+    skill: string;
+    url: string;
+}
+export interface RenderingTemplateDefinition {
+    /** Unique template id: "collection:name" */
+    id: string;
+    /** Unique template name (kebab-case) */
+    name: string;
+    /** Display title */
+    title?: string;
+    /** Short description */
+    description: string;
+    /** Template type */
+    type: 'presentation' | 'document';
+    /** Tags for categorization */
+    tags?: string[];
+    /** Absolute paths to asset files */
+    assets: string[];
+    /** The template instructions (markdown) */
+    instructions: string;
+}
+export type RenderingTemplateDefinitionRef = Omit<RenderingTemplateDefinition, 'instructions'> & {
+    /** Absolute API path to fetch the full template definition */
+    path: string;
+};
+export interface AppManifest extends AppManifestData {
+    id: string;
+    account: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface AppInstallation {
+    id: string;
+    project: string;
+    manifest: string;
+    settings?: Record<string, any>;
+    created_at: string;
+    updated_at: string;
+}
+export interface AppInstallationWithManifest extends Omit<AppInstallation, 'manifest'> {
+    manifest: AppManifest;
+}
+export interface AppInstallationPayload {
+    app_id: string;
+    settings?: Record<string, any>;
+}
+export type AppInstallationKind = 'ui' | 'tools' | 'all';
+/**
+ * A description of the tools provided by an app
+ */
+export interface AppToolCollection {
+    /**
+     * The collection name
+     */
+    name: string;
+    /**
+     * Optional collection description
+     */
+    description?: string;
+    /**
+     * the tools provided by this collection
+     */
+    tools: {
+        name: string;
+        description?: string;
+    }[];
+}
+/**
+ * Information about a tool and its associated app installation.
+ * Used to look up which app provides a specific tool.
+ */
+export interface ProjectToolInfo {
+    /**
+     * The tool name
+     */
+    tool_name: string;
+    /**
+     * Optional tool description
+     */
+    tool_description?: string;
+    /**
+     * The app name that provides this tool
+     */
+    app_name: string;
+    /**
+     * The app installation ID
+     */
+    app_install_id: string;
+    /**
+     * The app installation settings.
+     * Only included for agent tokens, not user tokens (security: may contain API keys).
+     */
+    settings?: Record<string, any>;
+}
+/**
+ * OAuth authentication status for an MCP tool collection
+ */
+export interface OAuthAuthStatus {
+    collection_name: string;
+    authenticated: boolean;
+    mcp_server_url: string;
+    expires_at?: string;
+    scope?: string;
+}
+/**
+ * Response from OAuth authorization endpoint
+ */
+export interface OAuthAuthorizeResponse {
+    authorization_url: string;
+    state: string;
+}
+/**
+ * Response from OAuth metadata endpoint
+ */
+export interface OAuthMetadataResponse {
+    collection_name: string;
+    mcp_server_url: string;
+    metadata: any;
+}
+/**
+ * App navigation item display overrides.
+ * Allows customizing individual nav items for an app installation within the CompositeApp shell.
+ */
+export interface CompositeAppNavItemOverride {
+    /** Used as identifier to match the nav item to override -- does not change route path */
+    route: string;
+    /** Hide this nav item from the sidebar */
+    hidden?: boolean;
+    /** Override the displayed nav item label */
+    label?: string;
+    /** Override the displayed nav item icon (Lucide icon name or SVG content string) */
+    icon?: string;
+}
+/**
+ * Configuration entry for an individual app in the CompositeApp shell.
+ * References an app installation by name and allows customizing its appearance.
+ */
+export interface CompositeAppEntry {
+    /** App installation name (must match an installed app) */
+    appName: string;
+    /** Override the label displayed for the app */
+    labelOverride?: string;
+    /** Override the icon displayed for the app (Lucide icon name or SVG content string) */
+    iconOverride?: string;
+    /** Overrides for navigation items provided by the app */
+    navigationOverrides?: CompositeAppNavItemOverride[];
+}
+/**
+ * Logo overrides for the CompositeApp shell header.
+ * When provided, these URLs replace the default Vertesia logo.
+ */
+export interface CompositeAppLogoOverrides {
+    /** URL for light mode logo (overrides default Vertesia logo) */
+    lightModeUrl?: string;
+    /** URL for dark mode logo (overrides default Vertesia logo) */
+    darkModeUrl?: string;
+}
+/**
+ * Message banner overrides for the shell header.
+*/
+export type CompositeAppMessageStyle = 'foreground' | 'info' | 'success' | 'attention' | 'destructive';
+export interface CompositeAppMessageOverrides {
+    /** Message text to display */
+    text?: string;
+    /** Whether the message is visible (defaults to true) */
+    visible?: boolean;
+    /** Text color style. Uses semantic colors */
+    style?: CompositeAppMessageStyle;
+}
+/**
+ * Switcher visibility overrides for the CompositeApp header.
+ */
+export interface CompositeAppSwitchersOverrides {
+    /** Whether to show the organization switcher (defaults to true) */
+    showOrganization?: boolean;
+    /** Whether to show the project switcher (defaults to true) */
+    showProject?: boolean;
+}
+/**
+ * Card display overrides for the CompositeApp in the App Portal.
+ * Similar to AppManifest display properties, but specific to the CompositeApp card.
+ * Allows customers to customize the app portal card (not otherwise possible if using a
+ * shared, Vertesia-managed manifest across accounts).
+ */
+export interface CompositeAppCardOverrides {
+    /** Whether to show the CompositeApp card in App Portal (default: false) */
+    visible?: boolean;
+    /** Override the card label (default: "Composite App") */
+    label?: string;
+    /** Override the card description */
+    description?: string;
+    /** Override the card icon (Lucide icon name or SVG content string) */
+    icon?: string;
+    /** Override the card color (e.g., "blue", "red", "purple") */
+    color?: string;
+}
+/**
+ * CompositeApp shell configuration.
+ * This is the main configuration interface for storing CompositeApp settings.
+ * Used as the MongoDB model for persisting CompositeApp configurations.
+ */
+export interface CompositeAppConfig {
+    /**
+     * The unique identifier for this CompositeApp configuration
+     * Undefined if the configuration doesn't exists yet.
+    */
+    id?: string;
+    /** The project this CompositeApp belongs to */
+    project: string;
+    /** Card display overrides (includes visibility) */
+    card?: CompositeAppCardOverrides;
+    /** Optional logo overrides (replaces default Vertesia logo) */
+    logo?: CompositeAppLogoOverrides;
+    /** Optional message banner overrides */
+    message?: CompositeAppMessageOverrides;
+    /** Optional switcher visibility overrides */
+    switchers?: CompositeAppSwitchersOverrides;
+    /** List of apps to include in the CompositeApp */
+    apps: CompositeAppEntry[];
+}
+export type CompositeAppConfigPayload = Partial<Omit<CompositeAppConfig, 'id' | 'project'>>;
+export {};

package/lib/types/apps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/apps.ts"],"names":[],"mappings":"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"}

package/lib/types/ask-user.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Types for ask_user tool UX configuration.
+ * These types enable the model to transmit structured UX parameters
+ * that render as interactive widgets instead of plain text.
+ */
+/** Option for user selection in ask_user widget */
+export interface AskUserOption {
+    /** Unique identifier returned when this option is selected */
+    id: string;
+    /** Display text for the option */
+    label: string;
+    /** Optional tooltip/description shown on hover */
+    description?: string;
+}
+/** UX configuration for ask_user messages */
+export interface AskUserUxConfig {
+    /** Predefined options for the user to select from */
+    options?: AskUserOption[];
+    /** Visual style variant */
+    variant?: 'default' | 'warning' | 'info' | 'success';
+    /** Allow selecting multiple options (renders checkboxes instead of buttons) */
+    multiSelect?: boolean;
+    /** Show text input for free-form response */
+    allowFreeResponse?: boolean;
+    /** Placeholder text for free-form input */
+    placeholder?: string;
+}
+/** Message details structure for REQUEST_INPUT messages with UX config */
+export interface AskUserMessageDetails {
+    /** UX configuration for rendering the ask_user widget */
+    ux?: AskUserUxConfig;
+}

package/lib/types/ask-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-user.d.ts","sourceRoot":"","sources":["../../src/ask-user.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC1B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC5B,qDAAqD;IACrD,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,2BAA2B;IAC3B,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IACrD,+EAA+E;IAC/E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IAClC,yDAAyD;IACzD,EAAE,CAAC,EAAE,eAAe,CAAC;CACxB"}

package/lib/types/audit-trail.d.ts

@@ -0,0 +1,49 @@
+export type AuditAction = 'create' | 'update' | 'delete' | 'bulk_update' | 'bulk_delete' | 'attach' | 'detach' | 'publish' | 'unpublish';
+export interface AuditTrailEvent {
+    event_type: 'audit';
+    action: AuditAction;
+    resource_type: string;
+    resource_id: string;
+    timestamp: string;
+    request_id: string;
+    status: number;
+    success: boolean;
+    principal_id: string | null;
+    principal_type: string | null;
+    principal_user_id: string | null;
+    roles: string[];
+    account_id: string | null;
+    project_id: string | null;
+    tenant_id: string | null;
+    account_name: string | null;
+    project_name: string | null;
+}
+export interface AuditTrailQuery {
+    /** Filter by action types */
+    actions?: AuditAction[];
+    /** Filter by resource types */
+    resourceTypes?: string[];
+    /** Filter by resource ID */
+    resourceId?: string;
+    /** Filter by principal ID (matches principal_id column — API keys, service accounts) */
+    principalId?: string;
+    /** Filter by principal user ID (matches principal_user_id column — human users) */
+    principalUserId?: string;
+    /** Filter by project ID */
+    projectId?: string;
+    /** Start time (ISO string) */
+    from?: string;
+    /** End time (ISO string) */
+    to?: string;
+    /** Pagination: number of items to return (default 50, max 200) */
+    limit?: number;
+    /** Pagination: offset */
+    offset?: number;
+}
+export interface AuditTrailResponse {
+    events: AuditTrailEvent[];
+    /** Whether there are more events after this page */
+    hasNext: boolean;
+    limit: number;
+    offset: number;
+}

package/lib/types/audit-trail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-trail.d.ts","sourceRoot":"","sources":["../../src/audit-trail.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GACjB,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,aAAa,GACb,aAAa,GACb,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,CAAC;AAElB,MAAM,WAAW,eAAe;IAC5B,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC5B,6BAA6B;IAC7B,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,+BAA+B;IAC/B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IAC/B,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB"}

package/lib/types/channels.d.ts

@@ -0,0 +1,21 @@
+import { EmailChannel, UserChannel } from "./interaction.js";
+/**
+ * Find the email channel from a list of channels.
+ * @returns The email channel if found, undefined otherwise
+ */
+export declare function findEmailChannel(channels?: UserChannel[]): EmailChannel | undefined;
+/**
+ * Check if email channel is enabled in the channels list.
+ */
+export declare function hasEmailChannel(channels?: UserChannel[]): boolean;
+/**
+ * Update the email channel in a channels array (immutable).
+ * Returns a new array with the updated channel.
+ * If no email channel exists and to_email is provided, creates one.
+ */
+export declare function updateEmailChannel(channels: UserChannel[] | undefined, updates: Partial<Omit<EmailChannel, "type">>): UserChannel[];
+/**
+ * Update email threading info after sending or receiving an email.
+ * Adds the new messageId to references and updates in_reply_to.
+ */
+export declare function updateEmailThreading(channels: UserChannel[] | undefined, messageId: string, subject?: string): UserChannel[];

package/lib/types/channels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../../src/channels.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAkB,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE7E;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,YAAY,GAAG,SAAS,CAEnF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,OAAO,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAC9B,QAAQ,EAAE,WAAW,EAAE,GAAG,SAAS,EACnC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,GAC7C,WAAW,EAAE,CAoBf;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,WAAW,EAAE,GAAG,SAAS,EACnC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACjB,WAAW,EAAE,CAcf"}

package/lib/types/common.d.ts

@@ -0,0 +1,31 @@
+export interface FindPayload {
+    query: Record<string, any>;
+    offset?: number;
+    limit?: number;
+    select?: string;
+    all_revisions?: boolean;
+    from_root?: string;
+}
+export interface GenericCommandResponse {
+    status: string;
+    message: string;
+    err?: any;
+    details?: any;
+}
+export interface BulkOperationPayload {
+    /**
+     * The operation name
+     */
+    name: "change_type" | "delete" | "start_workflow" | "update";
+    /**
+     * The IDs of the objects to operate on
+     */
+    ids: string[];
+    /**
+     * The operation parameters.
+     */
+    params: Record<string, any>;
+}
+export interface BulkOperationResult {
+    status: "in_progress" | "completed" | "failed";
+}

package/lib/types/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/common.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,WAAW,sBAAsB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,OAAO,CAAC,EAAE,GAAG,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACjC;;OAEG;IACH,IAAI,EAAE,aAAa,GAAG,QAAQ,GAAG,gBAAgB,GAAG,QAAQ,CAAC;IAE7D;;OAEG;IACH,GAAG,EAAE,MAAM,EAAE,CAAC;IAEd;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAChC,MAAM,EAAE,aAAa,GAAG,WAAW,GAAG,QAAQ,CAAC;CAClD"}