@memberjunction/graphql-dataprovider 3.1.1 → 3.3.0

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
  */
@@ -2810,6 +2971,319 @@ declare class GraphQLComponentRegistryClient {
     SendComponentFeedback(params: ComponentFeedbackParams): Promise<ComponentFeedbackResponse>;
 }
 
+/**
+ * Client for file storage operations through GraphQL.
+ * This class provides an easy way to interact with file storage accounts from a client application.
+ *
+ * All operations use accountId (FileStorageAccount ID) as the primary identifier,
+ * supporting the enterprise model where storage accounts are organizational resources.
+ *
+ * @example
+ * ```typescript
+ * // Create the client
+ * const storageClient = new GraphQLFileStorageClient(graphQLProvider);
+ *
+ * // List objects in a directory
+ * const objects = await storageClient.ListObjects(accountId, 'documents/');
+ *
+ * // Create a pre-authenticated upload URL
+ * const uploadResult = await storageClient.CreatePreAuthUploadUrl(
+ *   accountId,
+ *   'documents/report.pdf',
+ *   'application/pdf'
+ * );
+ * ```
+ */
+declare class GraphQLFileStorageClient {
+    /**
+     * The GraphQLDataProvider instance used to execute GraphQL requests
+     * @private
+     */
+    private _dataProvider;
+    /**
+     * Creates a new GraphQLFileStorageClient instance.
+     * @param dataProvider The GraphQL data provider to use for queries
+     */
+    constructor(dataProvider: GraphQLDataProvider);
+    /**
+     * List objects in a storage account at the specified path.
+     *
+     * @param accountId The ID of the FileStorageAccount
+     * @param prefix The path prefix to list objects from (e.g., 'documents/')
+     * @param delimiter Optional delimiter for grouping results (default: '/')
+     * @returns A Promise that resolves to a StorageListResult
+     *
+     * @example
+     * ```typescript
+     * const result = await storageClient.ListObjects(accountId, 'documents/', '/');
+     * console.log('Files:', result.objects.filter(o => !o.isDirectory));
+     * console.log('Folders:', result.prefixes);
+     * ```
+     */
+    ListObjects(accountId: string, prefix?: string, delimiter?: string): Promise<StorageListResult>;
+    /**
+     * Check if a directory exists in the storage account.
+     *
+     * @param accountId The ID of the FileStorageAccount
+     * @param path The directory path to check
+     * @returns A Promise that resolves to true if the directory exists
+     */
+    DirectoryExists(accountId: string, path: string): Promise<boolean>;
+    /**
+     * Create a directory in the storage account.
+     *
+     * @param accountId The ID of the FileStorageAccount
+     * @param path The directory path to create
+     * @returns A Promise that resolves to true if the directory was created successfully
+     */
+    CreateDirectory(accountId: string, path: string): Promise<boolean>;
+    /**
+     * Check if an object exists in the storage account.
+     *
+     * @param accountId The ID of the FileStorageAccount
+     * @param objectName The name/path of the object to check
+     * @returns A Promise that resolves to true if the object exists
+     */
+    ObjectExists(accountId: string, objectName: string): Promise<boolean>;
+    /**
+     * Create a pre-authenticated URL for uploading a file.
+     *
+     * @param accountId The ID of the FileStorageAccount
+     * @param objectName The name/path of the object to upload
+     * @param contentType Optional content type for the file
+     * @returns A Promise that resolves to the upload URL and provider key
+     *
+     * @example
+     * ```typescript
+     * const result = await storageClient.CreatePreAuthUploadUrl(
+     *   accountId,
+     *   'documents/report.pdf',
+     *   'application/pdf'
+     * );
+     *
+     * // Use the upload URL to upload the file
+     * await fetch(result.uploadUrl, {
+     *   method: 'PUT',
+     *   body: fileContent,
+     *   headers: { 'Content-Type': 'application/pdf' }
+     * });
+     * ```
+     */
+    CreatePreAuthUploadUrl(accountId: string, objectName: string, contentType?: string): Promise<CreatePreAuthUploadUrlResult>;
+    /**
+     * Create a pre-authenticated URL for downloading a file.
+     *
+     * @param accountId The ID of the FileStorageAccount
+     * @param objectName The name/path of the object to download
+     * @returns A Promise that resolves to the download URL
+     *
+     * @example
+     * ```typescript
+     * const downloadUrl = await storageClient.CreatePreAuthDownloadUrl(
+     *   accountId,
+     *   'documents/report.pdf'
+     * );
+     *
+     * // Use the download URL
+     * window.open(downloadUrl, '_blank');
+     * ```
+     */
+    CreatePreAuthDownloadUrl(accountId: string, objectName: string): Promise<string>;
+    /**
+     * Delete an object from the storage account.
+     *
+     * @param accountId The ID of the FileStorageAccount
+     * @param objectName The name/path of the object to delete
+     * @returns A Promise that resolves to true if the object was deleted successfully
+     */
+    DeleteObject(accountId: string, objectName: string): Promise<boolean>;
+    /**
+     * Move/rename an object within the storage account.
+     *
+     * @param accountId The ID of the FileStorageAccount
+     * @param oldName The current name/path of the object
+     * @param newName The new name/path for the object
+     * @returns A Promise that resolves to true if the object was moved successfully
+     */
+    MoveObject(accountId: string, oldName: string, newName: string): Promise<boolean>;
+    /**
+     * Copy an object within the storage account.
+     *
+     * @param accountId The ID of the FileStorageAccount
+     * @param sourceName The source name/path of the object
+     * @param destinationName The destination name/path for the copy
+     * @returns A Promise that resolves to true if the object was copied successfully
+     */
+    CopyObject(accountId: string, sourceName: string, destinationName: string): Promise<boolean>;
+    /**
+     * Copy an object between two different storage accounts.
+     *
+     * @param sourceAccountId The ID of the source FileStorageAccount
+     * @param destinationAccountId The ID of the destination FileStorageAccount
+     * @param sourcePath The source path of the object
+     * @param destinationPath The destination path for the copy
+     * @returns A Promise that resolves to the copy result
+     */
+    CopyObjectBetweenAccounts(sourceAccountId: string, destinationAccountId: string, sourcePath: string, destinationPath: string): Promise<CopyBetweenAccountsResult>;
+    /**
+     * Search for files across one or more storage accounts.
+     *
+     * @param accountIds Array of FileStorageAccount IDs to search
+     * @param query The search query
+     * @param options Optional search options
+     * @returns A Promise that resolves to the search results
+     *
+     * @example
+     * ```typescript
+     * const results = await storageClient.SearchFiles(
+     *   [accountId1, accountId2],
+     *   'quarterly report',
+     *   {
+     *     maxResultsPerAccount: 10,
+     *     fileTypes: ['pdf', 'docx'],
+     *     searchContent: true
+     *   }
+     * );
+     *
+     * for (const accountResult of results.accountResults) {
+     *   console.log(`Results from ${accountResult.accountName}:`);
+     *   for (const file of accountResult.results) {
+     *     console.log(`  - ${file.name} (${file.relevance})`);
+     *   }
+     * }
+     * ```
+     */
+    SearchFiles(accountIds: string[], searchQuery: string, options?: FileSearchOptions): Promise<SearchAcrossAccountsResult>;
+}
+/**
+ * Metadata for a storage object
+ */
+interface StorageObjectMetadata {
+    /** The name of the object (filename) */
+    name: string;
+    /** The path to the object (directory) */
+    path: string;
+    /** The full path including name */
+    fullPath: string;
+    /** Size in bytes */
+    size: number;
+    /** MIME content type */
+    contentType: string;
+    /** Last modification date */
+    lastModified: Date;
+    /** Whether this is a directory */
+    isDirectory: boolean;
+    /** ETag for caching */
+    etag?: string;
+    /** Cache control header */
+    cacheControl?: string;
+}
+/**
+ * Result from listing storage objects
+ */
+interface StorageListResult {
+    /** Array of objects in the directory */
+    objects: StorageObjectMetadata[];
+    /** Array of subdirectory prefixes */
+    prefixes: string[];
+}
+/**
+ * Result from creating a pre-authenticated upload URL
+ */
+interface CreatePreAuthUploadUrlResult {
+    /** The URL to use for uploading */
+    uploadUrl: string;
+    /** The provider-specific key for the object */
+    providerKey?: string;
+}
+/**
+ * Result from copying an object between accounts
+ */
+interface CopyBetweenAccountsResult {
+    /** Whether the copy was successful */
+    success: boolean;
+    /** Human-readable message */
+    message: string;
+    /** Number of bytes transferred */
+    bytesTransferred?: number;
+    /** Name of the source account */
+    sourceAccount: string;
+    /** Name of the destination account */
+    destinationAccount: string;
+    /** Source path */
+    sourcePath: string;
+    /** Destination path */
+    destinationPath: string;
+}
+/**
+ * Options for file search operations
+ */
+interface FileSearchOptions {
+    /** Maximum results per account */
+    maxResultsPerAccount?: number;
+    /** Filter by file types (extensions) */
+    fileTypes?: string[];
+    /** Whether to search file content (not just names) */
+    searchContent?: boolean;
+}
+/**
+ * A single file search result
+ */
+interface FileSearchResult {
+    /** Path to the file */
+    path: string;
+    /** File name */
+    name: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME content type */
+    contentType: string;
+    /** Last modification date */
+    lastModified: Date;
+    /** Relevance score (0-1) */
+    relevance?: number;
+    /** Text excerpt showing the match */
+    excerpt?: string;
+    /** Whether the match was in the filename */
+    matchInFilename?: boolean;
+    /** Provider-specific object ID */
+    objectId?: string;
+}
+/**
+ * Search results for a single account
+ */
+interface AccountSearchResult {
+    /** The account ID */
+    accountId: string;
+    /** The account name */
+    accountName: string;
+    /** Whether the search was successful */
+    success: boolean;
+    /** Error message if search failed */
+    errorMessage?: string;
+    /** Search results */
+    results: FileSearchResult[];
+    /** Total matches found */
+    totalMatches?: number;
+    /** Whether there are more results */
+    hasMore: boolean;
+    /** Token for pagination */
+    nextPageToken?: string;
+}
+/**
+ * Result from searching across multiple accounts
+ */
+interface SearchAcrossAccountsResult {
+    /** Results grouped by account */
+    accountResults: AccountSearchResult[];
+    /** Total results returned across all accounts */
+    totalResultsReturned: number;
+    /** Number of accounts that were searched successfully */
+    successfulAccounts: number;
+    /** Number of accounts that failed to search */
+    failedAccounts: number;
+}
+
 /**
  * In-memory storage provider using nested Map structure for category isolation.
  * Used as a fallback when browser storage is not available.
@@ -2886,4 +3360,4 @@ declare class BrowserIndexedDBStorageProvider extends BrowserStorageProviderBase
     GetCategoryKeys(category: string): Promise<string[]>;
 }
 
-export { ActionItemInput, ActionItemOutput, BrowserIndexedDBStorageProvider, BrowserStorageProviderBase, 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, 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 SearchRegistryComponentsParams, type SimplePromptResult, SimpleRemoteEntity, SimpleRemoteEntityField, SimpleRemoteEntityOutput, 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 };