fireberry-api-client 1.0.0-beta.1 → 1.0.0-beta.2.1

package/README.md

@@ -9,6 +9,7 @@ A standalone, framework-agnostic TypeScript/JavaScript client for the Fireberry
 - Supports both ESM and CommonJS
 - Automatic retry on rate limits (429)
 - Optional metadata caching
+- Lookup field relationship detection
 - Fluent QueryBuilder API
 - Batch operations with auto-chunking
 - AbortController support for cancellation
@@ -16,11 +17,24 @@ A standalone, framework-agnostic TypeScript/JavaScript client for the Fireberry
 ## Installation
 
 ```bash
-npm install fireberry-api-client
+npm install fireberry-api-client@latest
 ```
 
 **Requirements:** Node.js 18+
 
+### Import Paths
+
+```typescript
+// Main export
+import { FireberryClient } from 'fireberry-api-client';
+
+// Utilities export
+import { getObjectIdFieldName } from 'fireberry-api-client/utils';
+
+// SDK adapter
+import { createSDKQueryBuilder } from 'fireberry-api-client/sdk';
+```
+
 ## Quick Start
 
 ```typescript
@@ -177,6 +191,15 @@ const objects = await client.metadata.getObjects();
 // Get fields for an object
 const fields = await client.metadata.getFields('1');
 
+// Get fields with lookup relationships (shows which object each lookup field references)
+const fieldsWithRelations = await client.metadata.getFields('1', {
+  includeLookupRelations: true
+});
+
+// Example: Find related object for a lookup field
+const primaryContact = fieldsWithRelations.fields.find(f => f.fieldName === 'primarycontactid');
+console.log(primaryContact?.relatedObjectType); // 2 (Contact)
+
 // Get dropdown values
 const values = await client.metadata.getFieldValues('1', 'statuscode');
 ```

package/dist/index.cjs

@@ -14,6 +14,7 @@ var __export = (target, all) => {
 var excludedFields_exports = {};
 __export(excludedFields_exports, {
   EXCLUDED_FIELDS_FOR_STAR_QUERY: () => exports.EXCLUDED_FIELDS_FOR_STAR_QUERY,
+  EXCLUDED_LOOKUP_FIELDS: () => EXCLUDED_LOOKUP_FIELDS,
   getExcludedFieldsForStarQuery: () => getExcludedFieldsForStarQuery,
   isExcludedFromStarQuery: () => isExcludedFromStarQuery
 });
@@ -26,7 +27,7 @@ function getExcludedFieldsForStarQuery(objectType) {
   const objectTypeStr = String(objectType);
   return exports.EXCLUDED_FIELDS_FOR_STAR_QUERY[objectTypeStr] || [];
 }
-exports.EXCLUDED_FIELDS_FOR_STAR_QUERY = void 0;
+exports.EXCLUDED_FIELDS_FOR_STAR_QUERY = void 0; var EXCLUDED_LOOKUP_FIELDS;
 var init_excludedFields = __esm({
   "src/constants/excludedFields.ts"() {
     exports.EXCLUDED_FIELDS_FOR_STAR_QUERY = {
@@ -43,6 +44,7 @@ var init_excludedFields = __esm({
       "117": ["deletedon", "deletedby"]
       // Landing Page
     };
+    EXCLUDED_LOOKUP_FIELDS = ["deletedby", "deletedon"];
   }
 });
 
@@ -522,6 +524,13 @@ var FIELD_TYPE_MAPPINGS = {
 };
 
 // src/api/metadata.ts
+init_excludedFields();
+var ENDPOINTS = {
+  OBJECTS: "/metadata/records",
+  FIELDS: (objectType) => `/metadata/records/${objectType}/fields`,
+  FIELD_VALUES: (objectType, fieldName) => `/metadata/records/${objectType}/fields/${fieldName}/values`,
+  QUERY: "/api/query"
+};
 var MetadataAPI = class {
   constructor(client) {
     this.client = client;
@@ -545,7 +554,7 @@ var MetadataAPI = class {
     }
     const response = await this.client.request({
       method: "GET",
-      endpoint: "/metadata/records",
+      endpoint: ENDPOINTS.OBJECTS,
       signal
     });
     const result = {
@@ -560,30 +569,55 @@ var MetadataAPI = class {
    * Gets all fields for a specific object type
    *
    * @param objectType - The object type ID (e.g., '1' for Account)
-   * @param signal - Optional AbortSignal for cancellation
+   * @param options - Optional settings
+   * @param options.includeLookupRelations - If true, fetches related object types for lookup fields (requires additional API call)
+   * @param options.signal - Optional AbortSignal for cancellation
    * @returns List of fields with metadata
    *
    * @example
    * ```typescript
    * const result = await client.metadata.getFields('1');
    * console.log(result.fields); // [{ fieldName: 'accountid', label: 'Account ID', ... }, ...]
+   *
+   * // With lookup relations
+   * const result = await client.metadata.getFields('1', { includeLookupRelations: true });
+   * console.log(result.fields.find(f => f.fieldName === 'primarycontactid')?.relatedObjectType); // 2
    * ```
    */
-  async getFields(objectType, signal) {
+  async getFields(objectType, options) {
     const objectTypeStr = String(objectType);
-    const cached = this.client.getCached("fields", objectTypeStr);
-    if (cached) {
-      return cached;
+    const opts = options instanceof AbortSignal ? { signal: options, includeLookupRelations: false } : { signal: options?.signal, includeLookupRelations: options?.includeLookupRelations };
+    if (!opts.includeLookupRelations) {
+      const cached = this.client.getCached("fields", objectTypeStr);
+      if (cached) {
+        return cached;
+      }
     }
     const response = await this.client.request({
       method: "GET",
-      endpoint: `/metadata/records/${objectTypeStr}/fields`,
-      signal
+      endpoint: ENDPOINTS.FIELDS(objectTypeStr),
+      signal: opts.signal
     });
-    const fields = (response.data || []).map((field) => ({
+    let fields = (response.data || []).map((field) => ({
       ...field,
       fieldType: FIELD_TYPE_MAPPINGS[field.systemFieldTypeId] || field.systemFieldTypeId
     }));
+    if (opts.includeLookupRelations) {
+      const lookupFields = fields.filter(
+        (field) => field.systemFieldTypeId === FIELD_TYPE_IDS.LOOKUP
+      );
+      if (lookupFields.length > 0) {
+        const lookupRelations = await this.fetchLookupRelations(
+          objectTypeStr,
+          lookupFields.map((f) => f.fieldName),
+          opts.signal
+        );
+        fields = fields.map((field) => ({
+          ...field,
+          relatedObjectType: lookupRelations.get(field.fieldName)
+        }));
+      }
+    }
     const result = {
       objectTypeId: objectTypeStr,
       fields,
@@ -593,6 +627,40 @@ var MetadataAPI = class {
     this.client.setCache("fields", objectTypeStr, result);
     return result;
   }
+  /**
+   * Fetches related object types for lookup fields using the query endpoint.
+   * The query endpoint returns Columns metadata with fieldobjecttype even without records.
+   * Excludes fields that cause API errors (e.g., deletedby, deletedon).
+   */
+  async fetchLookupRelations(objectType, lookupFieldNames, signal) {
+    const relations = /* @__PURE__ */ new Map();
+    const queryableFields = lookupFieldNames.filter(
+      (fieldName) => !EXCLUDED_LOOKUP_FIELDS.includes(fieldName)
+    );
+    if (queryableFields.length === 0) {
+      return relations;
+    }
+    const response = await this.client.request({
+      method: "POST",
+      endpoint: ENDPOINTS.QUERY,
+      body: {
+        objecttype: objectType,
+        fields: queryableFields.join(","),
+        query: "",
+        page_size: 1,
+        page_number: 1,
+        show_real_value: 0
+      },
+      signal
+    });
+    const columns = response.data?.Columns || [];
+    for (const column of columns) {
+      if (column.fieldobjecttype !== null && column.fieldobjecttype !== void 0) {
+        relations.set(column.fieldname, column.fieldobjecttype);
+      }
+    }
+    return relations;
+  }
   /**
    * Gets all possible values for a dropdown field
    *
@@ -619,7 +687,7 @@ var MetadataAPI = class {
     }
     const response = await this.client.request({
       method: "GET",
-      endpoint: `/metadata/records/${objectTypeStr}/fields/${fieldName}/values`,
+      endpoint: ENDPOINTS.FIELD_VALUES(objectTypeStr, fieldName),
       signal
     });
     const result = {