@memberjunction/graphql-dataprovider 2.122.1 → 2.123.0

package/dist/index.d.cts

@@ -5,6 +5,7 @@ import { UserViewEntityExtended } from '@memberjunction/core-entities';
 import { Observable } from 'rxjs';
 import { ExecuteAgentParams, ExecuteAgentResult } from '@memberjunction/ai-core-plus';
 import { ActionParam, ActionResult, EntityActionInvocationParams, EntityActionResult } from '@memberjunction/actions-base';
+import { ComponentSpec } from '@memberjunction/interactive-component-types';
 
 /**
  * Client for executing AI operations through GraphQL.
@@ -2280,480 +2281,6 @@ declare class GraphQLTestingClient {
     private handleError;
 }
 
-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;
-    /**
-     * Whether this parameter must be provided when executing the query.
-     */
-    isRequired: boolean;
-    /**
-     * 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;
-    /**
-     * Data type of the parameter (e.g., 'string', 'int', 'uniqueidentifier', 'datetime', 'decimal').
-     * This helps the component generator understand how to properly format and pass the parameter value.
-     */
-    type?: string;
-    /**
-     * Example value demonstrating the proper format for this parameter.
-     * Preferred over testValue for component generation as it aligns with SkipQueryParamInfo.SampleValue naming.
-     */
-    sampleValue?: string;
-    /**
-     * Description of the parameter and how it is used in the query. This is important for helping
-     * 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;
-    /**
-     * Optional array of diagrams that use Mermaid syntax to illustrate component design.
-     * When provided each entry in the array specifies a title, optional description and the mermaid content itself.
-     * Examples of diagrams include:
-     * - Flowcharts of the process the component implements
-     * - Entity-relationship diagrams of the data model the component uses
-     * - Sequence diagrams illustrating interactions between the components various parts
-     */
-    diagrams?: Array<{
-        title: string;
-        description?: string;
-        content: 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[];
-    /**
-     * Self-declared maturity level of the component. When a component is "in progress" and is not
-     * yet complete but is partially done, it can be marked as "incomplete". When it is functionally complete
-     * but not yet widely tested, it can be marked as "beta". When it is fully complete and tested, it can be marked
-     * as "production". This is intended to help architects and developers understand the readiness of a component
-     * for use in production systems.
-     */
-    readinessLevel?: "incomplete" | "beta" | "production";
-    /**
-     * If a component isn't complete or encounters problems in testing, this field can be used to
-     * track a work plan for completing or fixing the component. Generally this work plan string will contain
-     * a markdown formatted list of tasks to be done with rich explanations to allow developers (human+AI) to
-     * collaborate on completing the component.
-     */
-    workPlan?: string;
-}
-/**
- * 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
  */