@memberjunction/graphql-dataprovider 3.2.0 → 3.3.0

package/dist/index.d.cts

@@ -544,6 +544,15 @@ declare class GraphQLProviderConfigData extends ProviderConfigDataBase {
      */
     get MJAPIKey(): string;
     set MJAPIKey(key: string);
+    /**
+     * This optional parameter is used when authenticating with a MemberJunction user API key (format: mj_sk_*).
+     * When provided, it will be sent in the X-API-Key header. This authenticates as the specific user who owns the API key.
+     *
+     * Unlike MJAPIKey (system key), this is a user-specific key that can be used for automated access on behalf of a user.
+     * Use this when you want to make API calls as a specific user without requiring OAuth authentication.
+     */
+    get UserAPIKey(): string;
+    set UserAPIKey(key: string);
     /**
      * URL is the URL to the GraphQL endpoint
      */
@@ -566,8 +575,9 @@ declare class GraphQLProviderConfigData extends ProviderConfigDataBase {
      * @param includeSchemas optional, an array of schema names to include in the metadata. If not passed, all schemas are included
      * @param excludeSchemas optional, an array of schema names to exclude from the metadata. If not passed, no schemas are excluded
      * @param mjAPIKey optional, a shared secret key that is static and provided by the publisher of the MJAPI server.
+     * @param userAPIKey optional, a user-specific API key (mj_sk_* format) for authenticating as a specific user
      */
-    constructor(token: string, url: string, wsurl: string, refreshTokenFunction: RefreshTokenFunction, MJCoreSchemaName?: string, includeSchemas?: string[], excludeSchemas?: string[], mjAPIKey?: string);
+    constructor(token: string, url: string, wsurl: string, refreshTokenFunction: RefreshTokenFunction, MJCoreSchemaName?: string, includeSchemas?: string[], excludeSchemas?: string[], mjAPIKey?: string, userAPIKey?: string);
 }
 /**
  * The GraphQLDataProvider class is a data provider for MemberJunction that implements the IEntityDataProvider, IMetadataProvider, IRunViewProvider, IRunReportProvider, IRunQueryProvider interfaces and connects to the
@@ -763,7 +773,7 @@ declare class GraphQLDataProvider extends ProviderBase implements IEntityDataPro
     RefreshToken(): Promise<void>;
     private performTokenRefresh;
     static RefreshToken(): Promise<void>;
-    protected CreateNewGraphQLClient(url: string, token: string, sessionId: string, mjAPIKey: string): GraphQLClient;
+    protected CreateNewGraphQLClient(url: string, token: string, sessionId: string, mjAPIKey: string, userAPIKey?: string): GraphQLClient;
     private _innerCurrentUserQueryString;
     private _currentUserQuery;
     private userInfoString;
@@ -2222,6 +2232,157 @@ declare class GraphQLActionClient {
     private handleEntityActionError;
 }
 
+/**
+ * Result of creating an API key
+ */
+interface CreateAPIKeyResult {
+    /** Whether the operation succeeded */
+    Success: boolean;
+    /** The raw API key - show once and cannot be recovered */
+    RawKey?: string;
+    /** The database ID of the created key */
+    APIKeyID?: string;
+    /** Error message if operation failed */
+    Error?: string;
+}
+/**
+ * Parameters for creating an API key
+ */
+interface CreateAPIKeyParams {
+    /** Human-readable label for the key */
+    Label: string;
+    /** Optional description */
+    Description?: string;
+    /** Optional expiration date */
+    ExpiresAt?: Date;
+    /** Optional scope IDs to assign */
+    ScopeIDs?: string[];
+}
+/**
+ * Result of revoking an API key
+ */
+interface RevokeAPIKeyResult {
+    /** Whether the operation succeeded */
+    Success: boolean;
+    /** Error message if operation failed */
+    Error?: string;
+}
+/**
+ * Client for encryption-related GraphQL operations.
+ *
+ * This client provides methods for operations that require server-side
+ * cryptographic processing, such as API key generation. These operations
+ * cannot be performed client-side because they require secure random
+ * number generation and cryptographic hashing that must match the
+ * server's validation logic.
+ *
+ * @example
+ * ```typescript
+ * // Create the client
+ * const encryptionClient = new GraphQLEncryptionClient(graphQLProvider);
+ *
+ * // Create a new API key
+ * const result = await encryptionClient.CreateAPIKey({
+ *   Label: 'My Integration Key',
+ *   Description: 'Used for external service access',
+ *   ExpiresAt: new Date('2025-12-31'),
+ *   ScopeIDs: ['scope-id-1', 'scope-id-2']
+ * });
+ *
+ * if (result.Success) {
+ *   // Show rawKey to user ONCE - cannot be recovered
+ *   console.log('Save this key:', result.RawKey);
+ * }
+ * ```
+ */
+declare class GraphQLEncryptionClient {
+    /**
+     * The GraphQLDataProvider instance used to execute GraphQL requests
+     */
+    private _dataProvider;
+    /**
+     * Creates a new GraphQLEncryptionClient instance.
+     * @param dataProvider The GraphQL data provider to use for queries
+     */
+    constructor(dataProvider: GraphQLDataProvider);
+    /**
+     * Creates a new API key with secure server-side cryptographic hashing.
+     *
+     * This method calls the server to:
+     * 1. Generate a cryptographically secure random API key
+     * 2. Hash the key using SHA-256 for secure storage
+     * 3. Store only the hash in the database
+     * 4. Return the raw key ONCE
+     *
+     * **CRITICAL**: The raw key is returned only once and cannot be recovered.
+     * Instruct users to save it immediately in a secure location.
+     *
+     * @param params Configuration for the new API key
+     * @returns Result with raw key (show once!) and database ID
+     *
+     * @example
+     * ```typescript
+     * const result = await client.CreateAPIKey({
+     *   Label: 'Production Integration',
+     *   Description: 'API access for our CRM system',
+     *   ExpiresAt: new Date('2025-12-31'),
+     *   ScopeIDs: ['entities:read', 'entities:write']
+     * });
+     *
+     * if (result.Success) {
+     *   alert(`Save this key now! It won't be shown again:\n${result.RawKey}`);
+     * } else {
+     *   console.error('Failed to create key:', result.Error);
+     * }
+     * ```
+     */
+    CreateAPIKey(params: CreateAPIKeyParams): Promise<CreateAPIKeyResult>;
+    /**
+     * Creates the variables for the CreateAPIKey mutation
+     * @param params The API key creation parameters
+     * @returns The mutation variables
+     */
+    private createAPIKeyVariables;
+    /**
+     * Executes the CreateAPIKey mutation
+     * @param variables The mutation variables
+     * @returns The GraphQL result
+     */
+    private executeCreateAPIKeyMutation;
+    /**
+     * Processes the result of the CreateAPIKey mutation
+     * @param result The GraphQL result
+     * @returns The processed result
+     */
+    private processCreateAPIKeyResult;
+    /**
+     * Handles errors in the CreateAPIKey operation
+     * @param e The error
+     * @returns An error result
+     */
+    private handleCreateAPIKeyError;
+    /**
+     * Revokes an API key, permanently disabling it.
+     *
+     * Once revoked, an API key cannot be reactivated. Users must create a new key.
+     *
+     * @param apiKeyId The database ID of the API key to revoke
+     * @returns Result indicating success or failure
+     *
+     * @example
+     * ```typescript
+     * const result = await client.RevokeAPIKey('key-uuid-here');
+     *
+     * if (result.Success) {
+     *   console.log('API key has been revoked');
+     * } else {
+     *   console.error('Failed to revoke:', result.Error);
+     * }
+     * ```
+     */
+    RevokeAPIKey(apiKeyId: string): Promise<RevokeAPIKeyResult>;
+}
+
 /**
  * Parameters for running a test
  */
@@ -3199,4 +3360,4 @@ declare class BrowserIndexedDBStorageProvider extends BrowserStorageProviderBase
     GetCategoryKeys(category: string): Promise<string[]>;
 }
 
-export { type AccountSearchResult, ActionItemInput, ActionItemOutput, BrowserIndexedDBStorageProvider, BrowserStorageProviderBase, type ComponentDependencyTree, type ComponentSpecWithHash, type CopyBetweenAccountsResult, type CreatePreAuthUploadUrlResult, type CreateQueryInput, type CreateQueryResult, type DeleteQueryOptionsInput, type DeleteQueryResult, type EmbedTextParams, type EmbedTextResult, type ExecuteSimplePromptParams, FieldMapper, type FileSearchOptions, type FileSearchResult, GetDataOutput, type GetQueryDataByNameSystemUserInput, type GetQueryDataSystemUserInput, type GetRegistryComponentParams, GraphQLAIClient, GraphQLActionClient, GraphQLComponentRegistryClient, GraphQLDataProvider, GraphQLFileStorageClient, GraphQLProviderConfigData, GraphQLSystemUserClient, GraphQLTestingClient, GraphQLTransactionGroup, type MJ_MetadataDB, type QueryEntity, type QueryField, type QueryParameter, type QueryPermission, type QueryPermissionInput, type RegistryComponentSearchResult, RoleInput, RolesAndUsersInput, type RunAIPromptParams, type RunAIPromptResult, type RunDynamicViewSystemUserInput, type RunQuerySystemUserResult, type RunTestParams, type RunTestResult, type RunTestSuiteParams, type RunTestSuiteResult, type RunViewByIDSystemUserInput, type RunViewByNameSystemUserInput, type RunViewSystemUserInput, type RunViewSystemUserResult, type RunViewSystemUserResultRow, type SearchAcrossAccountsResult, type SearchRegistryComponentsParams, type SimplePromptResult, SimpleRemoteEntity, SimpleRemoteEntityField, SimpleRemoteEntityOutput, type StorageListResult, type StorageObjectMetadata, SyncDataAction, SyncDataResult, SyncRolesAndUsersResult, type TestExecutionProgress, type UpdateQueryInput, type UpdateQueryResult, UserInput, setupGraphQLClient };
+export { type AccountSearchResult, ActionItemInput, ActionItemOutput, BrowserIndexedDBStorageProvider, BrowserStorageProviderBase, type ComponentDependencyTree, type ComponentSpecWithHash, type CopyBetweenAccountsResult, type CreateAPIKeyParams, type CreateAPIKeyResult, type CreatePreAuthUploadUrlResult, type CreateQueryInput, type CreateQueryResult, type DeleteQueryOptionsInput, type DeleteQueryResult, type EmbedTextParams, type EmbedTextResult, type ExecuteSimplePromptParams, FieldMapper, type FileSearchOptions, type FileSearchResult, GetDataOutput, type GetQueryDataByNameSystemUserInput, type GetQueryDataSystemUserInput, type GetRegistryComponentParams, GraphQLAIClient, GraphQLActionClient, GraphQLComponentRegistryClient, GraphQLDataProvider, GraphQLEncryptionClient, GraphQLFileStorageClient, GraphQLProviderConfigData, GraphQLSystemUserClient, GraphQLTestingClient, GraphQLTransactionGroup, type MJ_MetadataDB, type QueryEntity, type QueryField, type QueryParameter, type QueryPermission, type QueryPermissionInput, type RegistryComponentSearchResult, type RevokeAPIKeyResult, RoleInput, RolesAndUsersInput, type RunAIPromptParams, type RunAIPromptResult, type RunDynamicViewSystemUserInput, type RunQuerySystemUserResult, type RunTestParams, type RunTestResult, type RunTestSuiteParams, type RunTestSuiteResult, type RunViewByIDSystemUserInput, type RunViewByNameSystemUserInput, type RunViewSystemUserInput, type RunViewSystemUserResult, type RunViewSystemUserResultRow, type SearchAcrossAccountsResult, type SearchRegistryComponentsParams, type SimplePromptResult, SimpleRemoteEntity, SimpleRemoteEntityField, SimpleRemoteEntityOutput, type StorageListResult, type StorageObjectMetadata, SyncDataAction, SyncDataResult, SyncRolesAndUsersResult, type TestExecutionProgress, type UpdateQueryInput, type UpdateQueryResult, UserInput, setupGraphQLClient };

package/dist/index.d.mts

@@ -544,6 +544,15 @@ declare class GraphQLProviderConfigData extends ProviderConfigDataBase {
      */
     get MJAPIKey(): string;
     set MJAPIKey(key: string);
+    /**
+     * This optional parameter is used when authenticating with a MemberJunction user API key (format: mj_sk_*).
+     * When provided, it will be sent in the X-API-Key header. This authenticates as the specific user who owns the API key.
+     *
+     * Unlike MJAPIKey (system key), this is a user-specific key that can be used for automated access on behalf of a user.
+     * Use this when you want to make API calls as a specific user without requiring OAuth authentication.
+     */
+    get UserAPIKey(): string;
+    set UserAPIKey(key: string);
     /**
      * URL is the URL to the GraphQL endpoint
      */
@@ -566,8 +575,9 @@ declare class GraphQLProviderConfigData extends ProviderConfigDataBase {
      * @param includeSchemas optional, an array of schema names to include in the metadata. If not passed, all schemas are included
      * @param excludeSchemas optional, an array of schema names to exclude from the metadata. If not passed, no schemas are excluded
      * @param mjAPIKey optional, a shared secret key that is static and provided by the publisher of the MJAPI server.
+     * @param userAPIKey optional, a user-specific API key (mj_sk_* format) for authenticating as a specific user
      */
-    constructor(token: string, url: string, wsurl: string, refreshTokenFunction: RefreshTokenFunction, MJCoreSchemaName?: string, includeSchemas?: string[], excludeSchemas?: string[], mjAPIKey?: string);
+    constructor(token: string, url: string, wsurl: string, refreshTokenFunction: RefreshTokenFunction, MJCoreSchemaName?: string, includeSchemas?: string[], excludeSchemas?: string[], mjAPIKey?: string, userAPIKey?: string);
 }
 /**
  * The GraphQLDataProvider class is a data provider for MemberJunction that implements the IEntityDataProvider, IMetadataProvider, IRunViewProvider, IRunReportProvider, IRunQueryProvider interfaces and connects to the
@@ -763,7 +773,7 @@ declare class GraphQLDataProvider extends ProviderBase implements IEntityDataPro
     RefreshToken(): Promise<void>;
     private performTokenRefresh;
     static RefreshToken(): Promise<void>;
-    protected CreateNewGraphQLClient(url: string, token: string, sessionId: string, mjAPIKey: string): GraphQLClient;
+    protected CreateNewGraphQLClient(url: string, token: string, sessionId: string, mjAPIKey: string, userAPIKey?: string): GraphQLClient;
     private _innerCurrentUserQueryString;
     private _currentUserQuery;
     private userInfoString;
@@ -2222,6 +2232,157 @@ declare class GraphQLActionClient {
     private handleEntityActionError;
 }
 
+/**
+ * Result of creating an API key
+ */
+interface CreateAPIKeyResult {
+    /** Whether the operation succeeded */
+    Success: boolean;
+    /** The raw API key - show once and cannot be recovered */
+    RawKey?: string;
+    /** The database ID of the created key */
+    APIKeyID?: string;
+    /** Error message if operation failed */
+    Error?: string;
+}
+/**
+ * Parameters for creating an API key
+ */
+interface CreateAPIKeyParams {
+    /** Human-readable label for the key */
+    Label: string;
+    /** Optional description */
+    Description?: string;
+    /** Optional expiration date */
+    ExpiresAt?: Date;
+    /** Optional scope IDs to assign */
+    ScopeIDs?: string[];
+}
+/**
+ * Result of revoking an API key
+ */
+interface RevokeAPIKeyResult {
+    /** Whether the operation succeeded */
+    Success: boolean;
+    /** Error message if operation failed */
+    Error?: string;
+}
+/**
+ * Client for encryption-related GraphQL operations.
+ *
+ * This client provides methods for operations that require server-side
+ * cryptographic processing, such as API key generation. These operations
+ * cannot be performed client-side because they require secure random
+ * number generation and cryptographic hashing that must match the
+ * server's validation logic.
+ *
+ * @example
+ * ```typescript
+ * // Create the client
+ * const encryptionClient = new GraphQLEncryptionClient(graphQLProvider);
+ *
+ * // Create a new API key
+ * const result = await encryptionClient.CreateAPIKey({
+ *   Label: 'My Integration Key',
+ *   Description: 'Used for external service access',
+ *   ExpiresAt: new Date('2025-12-31'),
+ *   ScopeIDs: ['scope-id-1', 'scope-id-2']
+ * });
+ *
+ * if (result.Success) {
+ *   // Show rawKey to user ONCE - cannot be recovered
+ *   console.log('Save this key:', result.RawKey);
+ * }
+ * ```
+ */
+declare class GraphQLEncryptionClient {
+    /**
+     * The GraphQLDataProvider instance used to execute GraphQL requests
+     */
+    private _dataProvider;
+    /**
+     * Creates a new GraphQLEncryptionClient instance.
+     * @param dataProvider The GraphQL data provider to use for queries
+     */
+    constructor(dataProvider: GraphQLDataProvider);
+    /**
+     * Creates a new API key with secure server-side cryptographic hashing.
+     *
+     * This method calls the server to:
+     * 1. Generate a cryptographically secure random API key
+     * 2. Hash the key using SHA-256 for secure storage
+     * 3. Store only the hash in the database
+     * 4. Return the raw key ONCE
+     *
+     * **CRITICAL**: The raw key is returned only once and cannot be recovered.
+     * Instruct users to save it immediately in a secure location.
+     *
+     * @param params Configuration for the new API key
+     * @returns Result with raw key (show once!) and database ID
+     *
+     * @example
+     * ```typescript
+     * const result = await client.CreateAPIKey({
+     *   Label: 'Production Integration',
+     *   Description: 'API access for our CRM system',
+     *   ExpiresAt: new Date('2025-12-31'),
+     *   ScopeIDs: ['entities:read', 'entities:write']
+     * });
+     *
+     * if (result.Success) {
+     *   alert(`Save this key now! It won't be shown again:\n${result.RawKey}`);
+     * } else {
+     *   console.error('Failed to create key:', result.Error);
+     * }
+     * ```
+     */
+    CreateAPIKey(params: CreateAPIKeyParams): Promise<CreateAPIKeyResult>;
+    /**
+     * Creates the variables for the CreateAPIKey mutation
+     * @param params The API key creation parameters
+     * @returns The mutation variables
+     */
+    private createAPIKeyVariables;
+    /**
+     * Executes the CreateAPIKey mutation
+     * @param variables The mutation variables
+     * @returns The GraphQL result
+     */
+    private executeCreateAPIKeyMutation;
+    /**
+     * Processes the result of the CreateAPIKey mutation
+     * @param result The GraphQL result
+     * @returns The processed result
+     */
+    private processCreateAPIKeyResult;
+    /**
+     * Handles errors in the CreateAPIKey operation
+     * @param e The error
+     * @returns An error result
+     */
+    private handleCreateAPIKeyError;
+    /**
+     * Revokes an API key, permanently disabling it.
+     *
+     * Once revoked, an API key cannot be reactivated. Users must create a new key.
+     *
+     * @param apiKeyId The database ID of the API key to revoke
+     * @returns Result indicating success or failure
+     *
+     * @example
+     * ```typescript
+     * const result = await client.RevokeAPIKey('key-uuid-here');
+     *
+     * if (result.Success) {
+     *   console.log('API key has been revoked');
+     * } else {
+     *   console.error('Failed to revoke:', result.Error);
+     * }
+     * ```
+     */
+    RevokeAPIKey(apiKeyId: string): Promise<RevokeAPIKeyResult>;
+}
+
 /**
  * Parameters for running a test
  */
@@ -3199,4 +3360,4 @@ declare class BrowserIndexedDBStorageProvider extends BrowserStorageProviderBase
     GetCategoryKeys(category: string): Promise<string[]>;
 }
 
-export { type AccountSearchResult, ActionItemInput, ActionItemOutput, BrowserIndexedDBStorageProvider, BrowserStorageProviderBase, type ComponentDependencyTree, type ComponentSpecWithHash, type CopyBetweenAccountsResult, type CreatePreAuthUploadUrlResult, type CreateQueryInput, type CreateQueryResult, type DeleteQueryOptionsInput, type DeleteQueryResult, type EmbedTextParams, type EmbedTextResult, type ExecuteSimplePromptParams, FieldMapper, type FileSearchOptions, type FileSearchResult, GetDataOutput, type GetQueryDataByNameSystemUserInput, type GetQueryDataSystemUserInput, type GetRegistryComponentParams, GraphQLAIClient, GraphQLActionClient, GraphQLComponentRegistryClient, GraphQLDataProvider, GraphQLFileStorageClient, GraphQLProviderConfigData, GraphQLSystemUserClient, GraphQLTestingClient, GraphQLTransactionGroup, type MJ_MetadataDB, type QueryEntity, type QueryField, type QueryParameter, type QueryPermission, type QueryPermissionInput, type RegistryComponentSearchResult, RoleInput, RolesAndUsersInput, type RunAIPromptParams, type RunAIPromptResult, type RunDynamicViewSystemUserInput, type RunQuerySystemUserResult, type RunTestParams, type RunTestResult, type RunTestSuiteParams, type RunTestSuiteResult, type RunViewByIDSystemUserInput, type RunViewByNameSystemUserInput, type RunViewSystemUserInput, type RunViewSystemUserResult, type RunViewSystemUserResultRow, type SearchAcrossAccountsResult, type SearchRegistryComponentsParams, type SimplePromptResult, SimpleRemoteEntity, SimpleRemoteEntityField, SimpleRemoteEntityOutput, type StorageListResult, type StorageObjectMetadata, SyncDataAction, SyncDataResult, SyncRolesAndUsersResult, type TestExecutionProgress, type UpdateQueryInput, type UpdateQueryResult, UserInput, setupGraphQLClient };
+export { type AccountSearchResult, ActionItemInput, ActionItemOutput, BrowserIndexedDBStorageProvider, BrowserStorageProviderBase, type ComponentDependencyTree, type ComponentSpecWithHash, type CopyBetweenAccountsResult, type CreateAPIKeyParams, type CreateAPIKeyResult, type CreatePreAuthUploadUrlResult, type CreateQueryInput, type CreateQueryResult, type DeleteQueryOptionsInput, type DeleteQueryResult, type EmbedTextParams, type EmbedTextResult, type ExecuteSimplePromptParams, FieldMapper, type FileSearchOptions, type FileSearchResult, GetDataOutput, type GetQueryDataByNameSystemUserInput, type GetQueryDataSystemUserInput, type GetRegistryComponentParams, GraphQLAIClient, GraphQLActionClient, GraphQLComponentRegistryClient, GraphQLDataProvider, GraphQLEncryptionClient, GraphQLFileStorageClient, GraphQLProviderConfigData, GraphQLSystemUserClient, GraphQLTestingClient, GraphQLTransactionGroup, type MJ_MetadataDB, type QueryEntity, type QueryField, type QueryParameter, type QueryPermission, type QueryPermissionInput, type RegistryComponentSearchResult, type RevokeAPIKeyResult, RoleInput, RolesAndUsersInput, type RunAIPromptParams, type RunAIPromptResult, type RunDynamicViewSystemUserInput, type RunQuerySystemUserResult, type RunTestParams, type RunTestResult, type RunTestSuiteParams, type RunTestSuiteResult, type RunViewByIDSystemUserInput, type RunViewByNameSystemUserInput, type RunViewSystemUserInput, type RunViewSystemUserResult, type RunViewSystemUserResultRow, type SearchAcrossAccountsResult, type SearchRegistryComponentsParams, type SimplePromptResult, SimpleRemoteEntity, SimpleRemoteEntityField, SimpleRemoteEntityOutput, type StorageListResult, type StorageObjectMetadata, SyncDataAction, SyncDataResult, SyncRolesAndUsersResult, type TestExecutionProgress, type UpdateQueryInput, type UpdateQueryResult, UserInput, setupGraphQLClient };