@memberjunction/graphql-dataprovider 2.98.0 → 2.100.0

package/dist/index.d.cts

@@ -1422,9 +1422,9 @@ interface RunViewSystemUserInput {
  */
 interface RunViewSystemUserResultRow {
     /**
-     * Unique identifier of the record
+     * Primary key fields and values for the record
      */
-    ID: string;
+    PrimaryKey: KeyValuePair[];
     /**
      * ID of the entity type this record belongs to
      */
@@ -2035,4 +2035,753 @@ declare class GraphQLActionClient {
     private handleEntityActionError;
 }
 
-export { ActionItemInput, ActionItemOutput, type CreateQueryInput, type CreateQueryResult, type DeleteQueryOptionsInput, type DeleteQueryResult, type EmbedTextParams, type EmbedTextResult, type ExecuteSimplePromptParams, FieldMapper, GetDataOutput, type GetQueryDataByNameSystemUserInput, type GetQueryDataSystemUserInput, GraphQLAIClient, GraphQLActionClient, GraphQLDataProvider, GraphQLProviderConfigData, GraphQLSystemUserClient, GraphQLTransactionGroup, type QueryEntity, type QueryField, type QueryParameter, type QueryPermission, type QueryPermissionInput, RoleInput, RolesAndUsersInput, type RunAIAgentParams, type RunAIAgentResult, type RunAIPromptParams, type RunAIPromptResult, type RunDynamicViewSystemUserInput, type RunQuerySystemUserResult, type RunViewByIDSystemUserInput, type RunViewByNameSystemUserInput, type RunViewSystemUserInput, type RunViewSystemUserResult, type RunViewSystemUserResultRow, type SimplePromptResult, SimpleRemoteEntity, SimpleRemoteEntityField, SimpleRemoteEntityOutput, SyncDataAction, SyncDataResult, SyncRolesAndUsersResult, type UpdateQueryInput, type UpdateQueryResult, UserInput, setupGraphQLClient };
+interface ComponentDataRequirements {
+    /**
+     * How the component gets its data
+     * - 'views': Fetches data at runtime using MJ RunView()
+     * - 'queries': Fetches data at runtime using MJ RunQuery()
+     * - 'hybrid': Uses both views and queries, depending on the context
+     */
+    mode: 'views' | 'queries' | 'hybrid';
+    /**
+     * Describes the entities and fields the component will access to fulfill user requirements.
+     */
+    entities: ComponentEntityDataRequirement[];
+    /**
+     * Stored Queries that the component will use to fetch data.
+     */
+    queries: ComponentQueryDataRequirement[];
+    /**
+     * Description of data access patterns
+     */
+    description?: string;
+}
+/**
+ * Describes how a component will use a specific query in MemberJunction to fetch data
+ */
+type ComponentQueryDataRequirement = {
+    /**
+     * Query name, used along with categoryPath to identify the query
+     */
+    name: string;
+    /**
+     * Full path of the category for the query. Categories can be hierarchical so a full path might be
+     * 'Membership/Users/ActiveUsers'. This helps in organizing queries and avoiding name collisions.
+     */
+    categoryPath: string;
+    /**
+     * Description of the query and how/why the component will use it
+     */
+    description?: string;
+    /**
+     * A list of the fields that the component will use out of the possible fields returned by the query.
+     * Uses the @see SimpleEntityFieldInfo type to describe each field. **NOTE** not all of the fields are actually
+     * directly related to entity fields as some might be computed/etc, but SimpleEntityFieldInfo helps define some key aspects
+     * like the data type of the column and a description of the field.
+     */
+    fields: SimpleEntityFieldInfo[];
+    /**
+     * A list of the entities that are part of this query. This is vital information for matching query requests
+     * against existing queries
+     */
+    entityNames: string[];
+    /**
+     * Queries can have parameters (not all do). See @see ComponentQueryParameterValue for details.
+     */
+    parameters?: ComponentQueryParameterValue[];
+    /**
+     * This is only provided when requesting a NEW query be created. For existing queries, this will be undefined.
+     * This SQL can use Nunjucks syntax/templating for parameters including the custom filters defined in
+     */
+    newQuerySQL?: string;
+};
+/**
+ * Describes a single query parameter that a component will use when running a query.
+ */
+type ComponentQueryParameterValue = {
+    /**
+     * Name of the parameter
+     */
+    name: string;
+    /**
+     * Value of the parameter. If the value is '@runtime', it indicates that the component will determine the value at runtime.
+     * If anything other than '@runtime' is specified, it is a hardcoded value that the component will use.
+     */
+    value: string;
+    /**
+     * When specifying '@runtime' for the value, populate this field with a value that can be used to test the query to validate it runs. It doesn't need
+     * to be a value that is valid in the sense of being in the database, but is of the right type. For example if the
+     * parameter is a number, date or string, include a test value of that type. **Note** if the parameter is for a UNIQUEIDENTIFIER column
+     * type make sure to use a valid UUID format otherwise the query will FAIL.
+     */
+    testValue: string;
+    /**
+     * Description of the parameter and how it is used in the query. This is particular important if
+     * the value is '@runtime' as it helps the component developer understand what the parameter is for and how to determine its value.
+     */
+    description?: string;
+};
+/**
+ * Describes use of a single entity
+ */
+type ComponentEntityDataRequirement = {
+    /**
+     * Name of the entity (unique system-wide)
+     */
+    name: string;
+    /**
+     * Description of data in the entity
+     */
+    description?: string;
+    /**
+     * Fields to show the user
+     */
+    displayFields: string[];
+    /**
+     * Fields to filter on initially or via user interaction.
+     */
+    filterFields?: string[];
+    /**
+     * Fields to use when sorting
+     */
+    sortFields?: string[];
+    /**
+     * For the set of fields used in the combination of display, filter, and sort,
+     * this array is populated with additional metadata about each field. This will
+     * NOT include fields that are not used in the component.
+     */
+    fieldMetadata: SimpleEntityFieldInfo[];
+    /**
+     * When/Where/How components should use this data
+     */
+    usageContext?: string;
+    /**
+     * Array of permissions required by the component
+     */
+    permissionLevelNeeded: ComponentEntitySimplePermission[];
+};
+type ComponentEntitySimplePermission = 'read' | 'create' | 'update' | 'delete';
+/**
+ * Simple type to share more information about the relevant fields
+ * in an entity that are to be used in a component
+ **/
+type SimpleEntityFieldInfo = {
+    /**
+     * Name of the field
+     */
+    name: string;
+    /**
+     * Display sequence usually used for this field
+     */
+    sequence: number;
+    /**
+     * Whether this field is usually displayed in a user-facing view
+     */
+    defaultInView: boolean;
+    /**
+     * SQL Server type of the field, e.g., 'varchar', 'int', etc.
+     */
+    type: string;
+    /**
+     * Whether the field allows null values
+     */
+    allowsNull: boolean;
+    /**
+     * Whether the field is part of the primary key
+     */
+    isPrimaryKey: boolean;
+    /**
+     * Possible values for the field, if applicable
+     */
+    possibleValues?: string[];
+    /**
+     * Description of the field
+     */
+    description?: string;
+};
+
+/**
+ * Definition of a single property of a component.
+ */
+interface ComponentProperty {
+    /**
+     * The name of the property
+     */
+    name: string;
+    /**
+     * A description of what this property is used for
+     */
+    description: string;
+    /**
+     * The type of the property.
+     * It can be one of 'string', 'number', 'boolean', 'object', 'array', 'function', or 'any'.
+     * These types are for aligning users of the component. Components are in JavaScript and do not
+     * actually enforce types at runtime, but this is used to provide guidance for users (AI and Human)
+     */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'function' | 'any';
+    /**
+     * Indicates if this property is required for the component to function correctly.
+     * If true, the component will not work without this property being set.
+     */
+    required: boolean;
+    /**
+     * The default value, if any, for this property if it is not provided.
+     */
+    defaultValue?: any;
+    /**
+     * Optional list of possible values for this property.
+     */
+    possibleValues?: string[];
+}
+/**
+ * Definition of a single event of a component.
+ */
+interface ComponentEvent {
+    /**
+     * The name of the event
+     */
+    name: string;
+    /**
+     * A description of what this event does
+     */
+    description: string;
+    /**
+     * An array of parameters that this event can emit.
+     */
+    parameters?: ComponentEventParameter[];
+}
+interface ComponentEventParameter {
+    /**
+     * The name of the parameter
+     */
+    name: string;
+    /**
+     * A description of what this parameter is used for
+     */
+    description: string;
+    /**
+     * The type of the parameter.
+     * It can be one of 'string', 'number', 'boolean', 'object', 'array', 'function', or 'any'.
+     */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'function' | 'any';
+}
+
+/**
+ * Library dependency information for a component
+ */
+interface ComponentLibraryDependency {
+    /**
+     * Unique name of the library from our registry. Typically
+     * reuses npm style package names such as
+     * "recharts", "lodash", "dayjs", "antd" or "@memberjunction/lib-name"
+     */
+    name: string;
+    /**
+     * The global variable name used by the component to access the library in code.
+     * When the component is bootstrapped, the library is loaded into a variable in a
+     * Factory/wrapper function around it by the host.
+     */
+    globalVariable: string;
+    /**
+     * SemVer string describing minimum version requirement
+     * Example: "2.5.0" for fixed version, "^1.0.0" for minimum version
+     */
+    version?: string;
+}
+
+/**
+ * Specification for an interactive component
+ */
+declare class ComponentSpec {
+    name: string;
+    /**
+     * Components can be embedded or registry. Registry means we don't have the
+     * code directly here nor do we generate the code, we simply use the component from its registry
+     */
+    location: "embedded" | "registry";
+    /**
+     * Used when location === 'registry' - the unique name of a given registry without the @ sign
+     * for example MJ or Skip would be valid globally unique registry names (as registered with MemberJunction.org)
+     * You would not include @ here. Fully qualified component identifiers would be
+     * @Registry/Namespace/Name/Version but in the context of this field it is just the registry name.
+     */
+    registry?: string;
+    /**
+     * Used when location === "registry", a hierarchical namespace such as "crm/analytics/accounts". The combination of the
+     * namespace and name are how a registry component is loaded. Registry components might have
+     * a root level segment that starts with @ such as "@memberjunction/examples/entities" or if the root
+     * segment doesn't have @ that means the component is local to that registry
+     */
+    namespace?: string;
+    /**
+     * Used when location === "registry", a semantic versioning string such as
+     * "1.0.0"
+     * "^1.0.0"
+     * "~1.0.0"
+     * Follows conventions documented here: https://semver.org/ and https://docs.npmjs.com/about-semantic-versioning
+     */
+    version?: string;
+    /**
+     * Only used when location === 'registry', logic explaining why this component is being selected
+     * to serve a specific use case or requirement
+     */
+    selectionReasoning?: string;
+    /**
+     * When an architect decides to use an existing component as a base for a new version,
+     * they can set this flag to true. This indicates that the new version will be created
+     * based on the existing component based on the namespace/name/version specified above
+     */
+    createNewVersion?: boolean;
+    /**
+     * End-user friendly description of what the component does
+     */
+    description: string;
+    /**
+     * User-friendly name
+     */
+    title: string;
+    /**
+     * Self-declared type - some common options below, can be any string if the standard ones aren't sufficient
+     */
+    type: "report" | "dashboard" | "form" | "table" | "chart" | "navigation" | "search" | string;
+    /**
+     * JavaScript code
+     */
+    code: string;
+    /**
+     * A functional description of what the component should do in markdown.
+     *
+     * Describes:
+     * - Core functionality
+     * - Any business rules
+     * - Expected outcomes
+     * - UX considerations
+     */
+    functionalRequirements: string;
+    /**
+     * Describes the entities and queries a component requires to function.
+     */
+    dataRequirements?: ComponentDataRequirements;
+    /**
+     * Technical explanation of the component in markdown.
+     */
+    technicalDesign: string;
+    /**
+     * Properties the component accepts, if any
+     */
+    properties?: ComponentProperty[];
+    /**
+     * Events that the component emits, if any
+     */
+    events?: ComponentEvent[];
+    /**
+     * Metadata about methods the component supports, if any
+     */
+    methods?: ComponentMethodInfo;
+    /**
+     * Example of the component being used in JSX format. This is used to provide a clear example on the properties and
+     * event handling that the component supports.
+     */
+    exampleUsage: string;
+    /**
+     * Describes any other components this one depends on, if any
+     */
+    dependencies?: ComponentSpec[];
+    /**
+     * 3rd party lib dependencies, if any
+     */
+    libraries?: ComponentLibraryDependency[];
+    /**
+     * Relevant examples of components intended to inspire this component's creation
+     */
+    relevantExamples?: ComponentExample[];
+}
+/**
+ * Defines standard and custom methods a component implements
+ */
+interface ComponentMethodInfo {
+    standardMethodsSupported: {
+        print?: boolean;
+        refresh?: boolean;
+        getCurrentDataState?: boolean;
+        getDataStateHistory?: boolean;
+        validate?: boolean;
+        isDirty?: boolean;
+        reset?: boolean;
+        scrollTo?: boolean;
+        focus?: boolean;
+        invokeMethod?: boolean;
+        hasMethod?: boolean;
+    };
+    customMethods: CustomComponentMethod[];
+}
+/**
+ * Defines a single custom component method
+ */
+interface CustomComponentMethod {
+    name: string;
+    description: string;
+    parameters: Array<{
+        name: string;
+        type: string;
+        description?: string;
+    }>;
+    returnType: string;
+}
+/**
+ * Type that defines an example component used to inspire the creation
+ * of a new component. By definition these examples are located in a registry
+ * and can be found via the combination of their name and namespace. The optional
+ * properties can be used at runtime to store additional information as required
+ * for generation/inference needs
+ */
+type ComponentExample = {
+    name: string;
+    namespace: string;
+    version?: string;
+    registry?: string;
+    description?: string;
+    functionalRequirements?: string;
+    technicalDesign?: string;
+    /**
+     * Tracks a 0-1 number that indicates the relevance of this example to the containing ComponentSpec, can be used
+     * for ranking examples by importance/relevance
+     */
+    relevance?: number;
+    code?: string;
+    /**
+     * Optional runtime embedding vector calculated for description
+     */
+    descriptionVector?: number[];
+    /**
+     * Optional runtime embedding vector calculated for functional requirements
+     */
+    functionalRequirementsVector?: number[];
+    /**
+     * Optional runtime embedding vector calculated for technical design
+     */
+    technicalDesignVector?: number[];
+    /**
+     * Bag to hold any number of other runtime attributes
+     */
+    other?: any;
+};
+
+/**
+ * Parameters for getting a component from registry
+ */
+interface GetRegistryComponentParams {
+    /**
+     * Registry name (globally unique)
+     */
+    registryName: string;
+    /**
+     * Component namespace
+     */
+    namespace: string;
+    /**
+     * Component name
+     */
+    name: string;
+    /**
+     * Component version (optional, defaults to 'latest')
+     */
+    version?: string;
+    /**
+     * Optional hash for caching - if provided and matches, returns null
+     */
+    hash?: string;
+}
+/**
+ * Response from GetRegistryComponent with hash and caching metadata
+ */
+interface ComponentSpecWithHash {
+    /**
+     * The component specification (undefined if not modified)
+     */
+    specification?: ComponentSpec | string;
+    /**
+     * SHA-256 hash of the specification
+     */
+    hash: string;
+    /**
+     * Indicates if the component was not modified (304 response)
+     */
+    notModified: boolean;
+    /**
+     * Optional message from server
+     */
+    message?: string;
+}
+/**
+ * Parameters for searching registry components
+ */
+interface SearchRegistryComponentsParams {
+    /**
+     * Optional registry name filter
+     */
+    registryName?: string;
+    /**
+     * Optional namespace filter
+     */
+    namespace?: string;
+    /**
+     * Search query string
+     */
+    query?: string;
+    /**
+     * Component type filter
+     */
+    type?: string;
+    /**
+     * Tags to filter by
+     */
+    tags?: string[];
+    /**
+     * Maximum number of results
+     */
+    limit?: number;
+    /**
+     * Offset for pagination
+     */
+    offset?: number;
+}
+/**
+ * Search result for registry components
+ */
+interface RegistryComponentSearchResult {
+    /**
+     * Array of matching components
+     */
+    components: ComponentSpec[];
+    /**
+     * Total number of matches
+     */
+    total: number;
+    /**
+     * Current offset
+     */
+    offset: number;
+    /**
+     * Current limit
+     */
+    limit: number;
+}
+/**
+ * Dependency tree for a component
+ */
+interface ComponentDependencyTree {
+    /**
+     * Component ID
+     */
+    componentId: string;
+    /**
+     * Component name
+     */
+    name?: string;
+    /**
+     * Component namespace
+     */
+    namespace?: string;
+    /**
+     * Component version
+     */
+    version?: string;
+    /**
+     * Direct dependencies
+     */
+    dependencies?: ComponentDependencyTree[];
+    /**
+     * Whether this is a circular dependency
+     */
+    circular?: boolean;
+    /**
+     * Total count of all dependencies
+     */
+    totalCount?: number;
+}
+/**
+ * Client for executing Component Registry operations through GraphQL.
+ * This class provides an easy way to fetch components from external registries
+ * through the MJ API server, which handles authentication and caching.
+ *
+ * The GraphQLComponentRegistryClient follows the same naming convention as other GraphQL clients
+ * in the MemberJunction ecosystem, such as GraphQLAIClient and GraphQLActionClient.
+ *
+ * @example
+ * ```typescript
+ * // Create the client
+ * const registryClient = new GraphQLComponentRegistryClient(graphQLProvider);
+ *
+ * // Get a component from a registry
+ * const component = await registryClient.GetRegistryComponent({
+ *   registryName: "MJ",
+ *   namespace: "core/ui",
+ *   name: "DataGrid",
+ *   version: "1.0.0"
+ * });
+ *
+ * // Search for components
+ * const searchResult = await registryClient.SearchRegistryComponents({
+ *   query: "dashboard",
+ *   type: "dashboard",
+ *   limit: 10
+ * });
+ * ```
+ */
+declare class GraphQLComponentRegistryClient {
+    /**
+     * The GraphQLDataProvider instance used to execute GraphQL requests
+     * @private
+     */
+    private _dataProvider;
+    /**
+     * Creates a new GraphQLComponentRegistryClient instance.
+     * @param dataProvider The GraphQL data provider to use for queries
+     */
+    constructor(dataProvider: GraphQLDataProvider);
+    /**
+     * Get a specific component from a registry.
+     *
+     * This method fetches a component specification from an external registry
+     * through the MJ API server. The server handles authentication with the
+     * registry and may cache the result for performance.
+     *
+     * @param params The parameters for getting the component
+     * @returns A Promise that resolves to a ComponentSpec
+     *
+     * @example
+     * ```typescript
+     * const component = await registryClient.GetRegistryComponent({
+     *   registryName: "MJ",
+     *   namespace: "core/ui",
+     *   name: "DataGrid",
+     *   version: "2.0.0"
+     * });
+     *
+     * console.log('Component:', component.name);
+     * console.log('Description:', component.description);
+     * console.log('Code:', component.code);
+     * ```
+     */
+    GetRegistryComponent(params: GetRegistryComponentParams): Promise<ComponentSpec | null>;
+    /**
+     * Get a component from registry with hash and caching metadata.
+     * Returns the full response including hash and notModified flag.
+     *
+     * @param params - Parameters for fetching the component
+     * @returns Full response with specification, hash, and caching metadata
+     *
+     * @example
+     * ```typescript
+     * const response = await client.GetRegistryComponentWithHash({
+     *   registryName: 'MJ',
+     *   namespace: 'core/ui',
+     *   name: 'DataGrid',
+     *   version: '1.0.0',
+     *   hash: 'abc123...'
+     * });
+     *
+     * if (response.notModified) {
+     *   // Use cached version
+     * } else {
+     *   // Use response.specification
+     * }
+     * ```
+     */
+    GetRegistryComponentWithHash(params: GetRegistryComponentParams): Promise<ComponentSpecWithHash>;
+    /**
+     * Search for components in registries.
+     *
+     * This method searches for components across one or more registries
+     * based on the provided criteria. Results are paginated for performance.
+     *
+     * @param params The search parameters
+     * @returns A Promise that resolves to a RegistryComponentSearchResult
+     *
+     * @example
+     * ```typescript
+     * const searchResult = await registryClient.SearchRegistryComponents({
+     *   query: "dashboard",
+     *   type: "dashboard",
+     *   tags: ["analytics", "reporting"],
+     *   limit: 20,
+     *   offset: 0
+     * });
+     *
+     * console.log(`Found ${searchResult.total} components`);
+     * searchResult.components.forEach(component => {
+     *   console.log(`- ${component.name}: ${component.description}`);
+     * });
+     * ```
+     */
+    SearchRegistryComponents(params: SearchRegistryComponentsParams): Promise<RegistryComponentSearchResult>;
+    /**
+     * Resolve the dependency tree for a component.
+     *
+     * This method fetches the complete dependency tree for a component,
+     * including all transitive dependencies. The server handles circular
+     * dependency detection and marks them appropriately.
+     *
+     * @param registryId The registry ID
+     * @param componentId The component ID
+     * @returns A Promise that resolves to a ComponentDependencyTree
+     *
+     * @example
+     * ```typescript
+     * const dependencyTree = await registryClient.ResolveComponentDependencies(
+     *   "mj-central",
+     *   "component-123"
+     * );
+     *
+     * console.log(`Component has ${dependencyTree.totalCount} total dependencies`);
+     * if (dependencyTree.circular) {
+     *   console.warn('Circular dependency detected!');
+     * }
+     * ```
+     */
+    ResolveComponentDependencies(registryId: string, componentId: string): Promise<ComponentDependencyTree | null>;
+    /**
+     * Check if a specific version of a component exists in a registry.
+     *
+     * @param params The parameters for checking component existence
+     * @returns A Promise that resolves to true if the component exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const exists = await registryClient.ComponentExists({
+     *   registryId: "mj-central",
+     *   namespace: "core/ui",
+     *   name: "DataGrid",
+     *   version: "2.0.0"
+     * });
+     *
+     * if (exists) {
+     *   console.log('Component is available');
+     * }
+     * ```
+     */
+    ComponentExists(params: GetRegistryComponentParams): Promise<boolean>;
+    /**
+     * Get the latest version of a component.
+     *
+     * @param registryId The registry ID
+     * @param namespace The component namespace
+     * @param name The component name
+     * @returns A Promise that resolves to the latest version string or null
+     *
+     * @example
+     * ```typescript
+     * const latestVersion = await registryClient.GetLatestVersion(
+     *   "mj-central",
+     *   "core/ui",
+     *   "DataGrid"
+     * );
+     *
+     * console.log(`Latest version: ${latestVersion}`);
+     * ```
+     */
+    GetLatestVersion(registryName: string, namespace: string, name: string): Promise<string | null>;
+}
+
+export { ActionItemInput, ActionItemOutput, type ComponentDependencyTree, type ComponentSpecWithHash, type CreateQueryInput, type CreateQueryResult, type DeleteQueryOptionsInput, type DeleteQueryResult, type EmbedTextParams, type EmbedTextResult, type ExecuteSimplePromptParams, FieldMapper, GetDataOutput, type GetQueryDataByNameSystemUserInput, type GetQueryDataSystemUserInput, type GetRegistryComponentParams, GraphQLAIClient, GraphQLActionClient, GraphQLComponentRegistryClient, GraphQLDataProvider, GraphQLProviderConfigData, GraphQLSystemUserClient, GraphQLTransactionGroup, type QueryEntity, type QueryField, type QueryParameter, type QueryPermission, type QueryPermissionInput, type RegistryComponentSearchResult, RoleInput, RolesAndUsersInput, type RunAIAgentParams, type RunAIAgentResult, type RunAIPromptParams, type RunAIPromptResult, type RunDynamicViewSystemUserInput, type RunQuerySystemUserResult, type RunViewByIDSystemUserInput, type RunViewByNameSystemUserInput, type RunViewSystemUserInput, type RunViewSystemUserResult, type RunViewSystemUserResultRow, type SearchRegistryComponentsParams, type SimplePromptResult, SimpleRemoteEntity, SimpleRemoteEntityField, SimpleRemoteEntityOutput, SyncDataAction, SyncDataResult, SyncRolesAndUsersResult, type UpdateQueryInput, type UpdateQueryResult, UserInput, setupGraphQLClient };