fireberry-api-client 1.0.0-beta.1

package/dist/excludedFields-CGXgZN8Y.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Escapes special characters in query values to prevent query injection.
+ * This is a security measure to ensure user-provided values cannot modify
+ * the query structure or inject additional query logic.
+ *
+ * @param value - The value to escape
+ * @returns Escaped value safe for use in Fireberry queries
+ */
+declare function escapeQueryValue(value: string): string;
+/**
+ * Sanitizes a query string to ensure proper syntax for the Fireberry API
+ * Handles common syntax issues and removes extraneous elements
+ *
+ * @param query - Query string to sanitize
+ * @returns Sanitized query string
+ */
+declare function sanitizeQuery(query: string): string;
+/**
+ * Condition builder for fluent query construction
+ */
+interface ConditionBuilder {
+    /** Equals comparison (=) */
+    equals(value: string | number): QueryBuilder;
+    /** Not equals comparison (!=) */
+    notEquals(value: string | number): QueryBuilder;
+    /** Less than comparison (<) - works with numbers and dates */
+    lessThan(value: string | number): QueryBuilder;
+    /** Greater than comparison (>) - works with numbers and dates */
+    greaterThan(value: string | number): QueryBuilder;
+    /** Less than or equal (<=) - works with numbers ONLY (not dates!) */
+    lessThanOrEqual(value: string | number): QueryBuilder;
+    /** Greater than or equal (>=) - works with numbers ONLY (not dates!) */
+    greaterThanOrEqual(value: string | number): QueryBuilder;
+    /** Contains value (translates to start-with %value) */
+    contains(value: string): QueryBuilder;
+    /** Does not contain value (translates to not-start-with %value) */
+    notContains(value: string): QueryBuilder;
+    /** Starts with value (start-with) */
+    startsWith(value: string): QueryBuilder;
+    /** Does not start with value (not-start-with) */
+    notStartsWith(value: string): QueryBuilder;
+    /** Field is null (is-null) */
+    isNull(): QueryBuilder;
+    /** Field is not null (is-not-null) */
+    isNotNull(): QueryBuilder;
+}
+/**
+ * Fluent query builder for constructing Fireberry queries
+ *
+ * @example
+ * ```typescript
+ * // Build a query string
+ * const query = new QueryBuilder()
+ *   .where('statuscode').equals('1')
+ *   .and()
+ *   .where('emailaddress1').contains('@example.com')
+ *   .build();
+ * // Output: "(statuscode = 1) and (emailaddress1 start-with %@example.com)"
+ *
+ * // With select and execute (requires client)
+ * const result = await new QueryBuilder(client)
+ *   .objectType('1')
+ *   .select('accountid', 'name', 'emailaddress1')
+ *   .where('statuscode').equals('1')
+ *   .limit(100)
+ *   .execute();
+ * ```
+ */
+/**
+ * Client interface for query execution
+ */
+interface QueryClient {
+    query(options: {
+        objectType: string;
+        fields: string[];
+        query: string;
+        showRealValue: boolean;
+        sortBy?: string;
+        sortType?: 'asc' | 'desc';
+        limit?: number;
+        page?: number;
+        signal?: AbortSignal;
+    }): Promise<QueryResult>;
+}
+/**
+ * Query result type
+ */
+interface QueryResult {
+    records: Record<string, unknown>[];
+    total: number;
+    success: boolean;
+}
+declare class QueryBuilder {
+    private conditions;
+    private joinOperators;
+    private currentField;
+    private selectedFields;
+    private objectTypeId;
+    private sortByField;
+    private sortDirection;
+    private limitValue;
+    private pageNumber;
+    private showRealValueFlag;
+    private client;
+    /**
+     * Creates a new QueryBuilder
+     * @param client - Optional FireberryClient for executing queries
+     */
+    constructor(client?: QueryClient);
+    /**
+     * Sets the object type for the query
+     * @param objectType - Object type ID (e.g., '1' for Account)
+     */
+    objectType(objectType: string | number): this;
+    /**
+     * Adds fields to select
+     * @param fields - Field names to select
+     */
+    select(...fields: string[]): this;
+    /**
+     * Starts a new WHERE condition
+     * @param field - Field name to filter on
+     */
+    where(field: string): ConditionBuilder;
+    /**
+     * Adds an AND logical operator
+     */
+    and(): this;
+    /**
+     * Adds an OR logical operator
+     */
+    or(): this;
+    /**
+     * Sets the sort field and direction
+     * @param field - Field to sort by
+     * @param direction - Sort direction ('asc' or 'desc')
+     */
+    sortBy(field: string, direction?: 'asc' | 'desc'): this;
+    /**
+     * Sets the maximum number of records to return
+     * @param count - Maximum record count
+     */
+    limit(count: number): this;
+    /**
+     * Sets the page number for pagination
+     * @param page - Page number (1-based)
+     */
+    page(page: number): this;
+    /**
+     * Controls whether to show real values (labels) for dropdown fields
+     * @param show - Whether to show real values (default: true)
+     */
+    showRealValue(show: boolean): this;
+    /**
+     * Builds the query string from conditions
+     * @returns The built query string
+     */
+    build(): string;
+    /**
+     * Returns the selected fields array
+     * Useful for inspecting the query configuration
+     */
+    getFields(): string[];
+    /**
+     * Converts the query builder state to a payload compatible with @fireberry/sdk
+     *
+     * @returns Object with `fields` (comma-separated string) and `query` (filter string)
+     *
+     * @example
+     * ```typescript
+     * import FireberryClientSDK from '@fireberry/sdk/client';
+     * import { QueryBuilder } from 'fireberry-api-client';
+     *
+     * const sdk = new FireberryClientSDK();
+     * await sdk.initializeContext();
+     *
+     * const payload = new QueryBuilder()
+     *   .select('accountid', 'accountname')
+     *   .where('statuscode').equals('1')
+     *   .toSDKPayload();
+     *
+     * // Use with SDK
+     * const results = await sdk.api.query(1, payload);
+     * ```
+     */
+    toSDKPayload(): {
+        fields: string;
+        query: string;
+        page_size?: number;
+        page_number?: number;
+    };
+    /**
+     * Executes the query (requires client to be set)
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Query results
+     */
+    execute(signal?: AbortSignal): Promise<QueryResult>;
+    /**
+     * Creates a condition builder for the current field
+     */
+    private createConditionBuilder;
+    /**
+     * Adds a condition to the query
+     */
+    private addCondition;
+}
+
+/**
+ * Field Type System IDs from Fireberry CRM
+ * These UUIDs identify different field types in the metadata API
+ */
+declare const FIELD_TYPE_IDS: {
+    readonly DROPDOWN: "b4919f2e-2996-48e4-a03c-ba39fb64386c";
+    readonly LOOKUP: "a8fcdf65-91bc-46fd-82f6-1234758345a1";
+    readonly EMAIL: "c713d2f7-8fa9-43c3-8062-f07486eaf567";
+    readonly TEXT: "a1e7ed6f-5083-477b-b44c-9943a6181359";
+    readonly URL: "c820d32f-44df-4c2a-9c1e-18734e864fd5";
+    readonly LONG_TEXT: "80108f9d-1e75-40fa-9fa9-02be4ddc1da1";
+    readonly DATETIME: "ce972d02-5013-46d4-9d1d-f09df1ac346a";
+    readonly DATE: "83bf530c-e04c-462b-9ffc-a46f750fc072";
+    readonly HTML: "ed2ad39d-32fc-4585-8f5b-2e93463f050a";
+    readonly TELEPHONE: "3f62f67a-1cee-403a-bec6-aa02a9804edb";
+    readonly NUMERIC: "6a34bfe3-fece-4da1-9136-a7b1e5ae3319";
+};
+/**
+ * Human-readable mappings for field types
+ * Used for display purposes
+ */
+declare const FIELD_TYPE_MAPPINGS: Record<string, string>;
+
+/**
+ * Object Type ID to Primary Key Field Mapping
+ * Maps Fireberry object type IDs to their primary key field names
+ */
+declare const OBJECT_ID_MAP: Record<number, string>;
+/**
+ * Gets the primary key field name for a given object type
+ *
+ * @param objectTypeId - The numeric object type ID
+ * @returns The correct ID field name for the object type
+ */
+declare function getObjectIdFieldName(objectTypeId: string | number): string;
+
+/**
+ * Object Type ID to Name Field Mapping
+ * Maps Fireberry object type IDs to their display name field
+ */
+declare const OBJECT_NAME_MAP: Record<number, string>;
+/**
+ * Gets the display name field for a given object type
+ *
+ * @param objectTypeId - The numeric object type ID
+ * @returns The name field for the object type
+ */
+declare function getNameFieldByObjectType(objectTypeId: string | number): string;
+
+/**
+ * Fields to exclude from queries when using '*' (all fields) for specific object types
+ * These fields cause API errors when queried
+ */
+declare const EXCLUDED_FIELDS_FOR_STAR_QUERY: Record<string, string[]>;
+/**
+ * Checks if a field should be excluded from star queries for a given object type
+ *
+ * @param objectType - The object type ID
+ * @param fieldName - The field name to check
+ * @returns True if the field should be excluded
+ */
+declare function isExcludedFromStarQuery(objectType: string | number, fieldName: string): boolean;
+/**
+ * Gets the list of excluded fields for a given object type
+ *
+ * @param objectType - The object type ID
+ * @returns Array of field names to exclude, or empty array if none
+ */
+declare function getExcludedFieldsForStarQuery(objectType: string | number): string[];
+
+export { type ConditionBuilder as C, EXCLUDED_FIELDS_FOR_STAR_QUERY as E, FIELD_TYPE_IDS as F, OBJECT_ID_MAP as O, QueryBuilder as Q, FIELD_TYPE_MAPPINGS as a, OBJECT_NAME_MAP as b, getNameFieldByObjectType as c, getExcludedFieldsForStarQuery as d, escapeQueryValue as e, getObjectIdFieldName as g, isExcludedFromStarQuery as i, sanitizeQuery as s };

package/dist/fieldTypes-BLzJTzpI.d.cts

@@ -0,0 +1,67 @@
+/**
+ * Converts a field API name to its corresponding label field.
+ *
+ * Rules:
+ * - Special mappings (e.g., objectid → objecttitle)
+ * - Fields starting with "pcf" (custom fields): append "name" → pcf_field → pcf_fieldname
+ * - Fields ending with "code" (unless excluded): remove "code" → statuscode → status
+ * - Fields ending with "id" (unless excluded): replace "id" with "name" → accountid → accountname
+ * - All other fields: append "name"
+ *
+ * @param fieldName - The field API name
+ * @param objectType - The object type ID (required for object-specific overrides)
+ * @returns The corresponding label field, or empty string if no label field exists
+ */
+declare function getLabelFieldForField(fieldName: string, objectType: string | number): string;
+
+/**
+ * Checks if a field is a dropdown type based on its systemFieldTypeId
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns True if the field is a dropdown
+ */
+declare function isDropdownField(systemFieldTypeId: string): boolean;
+/**
+ * Checks if a field is a lookup type based on its systemFieldTypeId
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns True if the field is a lookup
+ */
+declare function isLookupField(systemFieldTypeId: string): boolean;
+/**
+ * Checks if a field is a dropdown or lookup type
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns True if the field is a dropdown or lookup
+ */
+declare function isDropdownOrLookupField(systemFieldTypeId: string): boolean;
+/**
+ * Checks if a field is a text type
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns True if the field is a text field
+ */
+declare function isTextField(systemFieldTypeId: string): boolean;
+/**
+ * Checks if a field is a numeric type
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns True if the field is a numeric field
+ */
+declare function isNumericField(systemFieldTypeId: string): boolean;
+/**
+ * Checks if a field is a date type (date or datetime)
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns True if the field is a date or datetime field
+ */
+declare function isDateField(systemFieldTypeId: string): boolean;
+/**
+ * Gets the field type name from its system ID
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns Human-readable field type name, or 'Unknown' if not found
+ */
+declare function getFieldTypeName(systemFieldTypeId: string): string;
+
+export { isLookupField as a, isDropdownOrLookupField as b, isTextField as c, isNumericField as d, isDateField as e, getFieldTypeName as f, getLabelFieldForField as g, isDropdownField as i };

package/dist/fieldTypes-BLzJTzpI.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Converts a field API name to its corresponding label field.
+ *
+ * Rules:
+ * - Special mappings (e.g., objectid → objecttitle)
+ * - Fields starting with "pcf" (custom fields): append "name" → pcf_field → pcf_fieldname
+ * - Fields ending with "code" (unless excluded): remove "code" → statuscode → status
+ * - Fields ending with "id" (unless excluded): replace "id" with "name" → accountid → accountname
+ * - All other fields: append "name"
+ *
+ * @param fieldName - The field API name
+ * @param objectType - The object type ID (required for object-specific overrides)
+ * @returns The corresponding label field, or empty string if no label field exists
+ */
+declare function getLabelFieldForField(fieldName: string, objectType: string | number): string;
+
+/**
+ * Checks if a field is a dropdown type based on its systemFieldTypeId
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns True if the field is a dropdown
+ */
+declare function isDropdownField(systemFieldTypeId: string): boolean;
+/**
+ * Checks if a field is a lookup type based on its systemFieldTypeId
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns True if the field is a lookup
+ */
+declare function isLookupField(systemFieldTypeId: string): boolean;
+/**
+ * Checks if a field is a dropdown or lookup type
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns True if the field is a dropdown or lookup
+ */
+declare function isDropdownOrLookupField(systemFieldTypeId: string): boolean;
+/**
+ * Checks if a field is a text type
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns True if the field is a text field
+ */
+declare function isTextField(systemFieldTypeId: string): boolean;
+/**
+ * Checks if a field is a numeric type
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns True if the field is a numeric field
+ */
+declare function isNumericField(systemFieldTypeId: string): boolean;
+/**
+ * Checks if a field is a date type (date or datetime)
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns True if the field is a date or datetime field
+ */
+declare function isDateField(systemFieldTypeId: string): boolean;
+/**
+ * Gets the field type name from its system ID
+ *
+ * @param systemFieldTypeId - The system field type ID from metadata
+ * @returns Human-readable field type name, or 'Unknown' if not found
+ */
+declare function getFieldTypeName(systemFieldTypeId: string): string;
+
+export { isLookupField as a, isDropdownOrLookupField as b, isTextField as c, isNumericField as d, isDateField as e, getFieldTypeName as f, getLabelFieldForField as g, isDropdownField as i };