CRUD Operations

/**
 * Create a new record in the specified entity
 * @param parameters - Create operation parameters
 * @returns Promise resolving to the created record ID or full record (with Prefer header)
 */
function Create(parameters: CreateParameters): Promise<string> | Promise<any> | string | any | BatchRequest;

interface CreateParameters extends BaseParameters {
    /** Entity logical name (e.g., "account", "contact") */
    entityName?: string;
    /** Override for non-standard entity set names */
    overriddenSetName?: string;
    /** Data object containing the field values to create */
    entity: object;
}

// Basic create
const accountId = await WebApiClient.Create({
    entityName: "account",
    entity: {
        name: "Contoso Corporation",
        telephone1: "555-0123",
        websiteurl: "https://contoso.com"
    }
});

// Create with return representation
const createdAccount = await WebApiClient.Create({
    entityName: "account",
    entity: { name: "Adventure Works" },
    headers: [{ key: "Prefer", value: "return=representation" }]
});

// Create with lookup relationship
await WebApiClient.Create({
    entityName: "contact",
    entity: {
        firstname: "John",
        lastname: "Doe",
        "parentcustomerid_account@odata.bind": "/accounts(" + accountId + ")"
    }
});

// Synchronous create
const syncResult = WebApiClient.Create({
    entityName: "account",
    entity: { name: "Sync Account" },
    async: false
});

/**
 * Retrieve records from CRM entities
 * @param parameters - Retrieve operation parameters
 * @returns Promise resolving to single record or array of records
 */
function Retrieve(parameters: RetrieveParameters): Promise<any> | any | BatchRequest;

interface RetrieveParameters extends BaseParameters {
    /** Entity logical name */
    entityName?: string;
    /** Override for non-standard entity set names */
    overriddenSetName?: string;
    /** Record GUID for single record retrieval */
    entityId?: string;
    /** Alternate key criteria for single record retrieval */
    alternateKey?: Array<Key>;
    /** OData query parameters (e.g., "?$select=name&$filter=...") */
    queryParams?: string;
    /** FetchXML query string for complex queries */
    fetchXml?: string;
    /** Override global pagination setting */
    returnAllPages?: boolean;
}

interface Key {
    property: string;
    value: string | number;
}

// Retrieve by ID
const account = await WebApiClient.Retrieve({
    entityName: "account",
    entityId: "12345678-1234-1234-1234-123456789abc",
    queryParams: "?$select=name,telephone1,websiteurl"
});

// Retrieve by alternate key
const contact = await WebApiClient.Retrieve({
    entityName: "contact",
    alternateKey: [
        { property: "emailaddress1", value: "john.doe@contoso.com" }
    ]
});

// Retrieve multiple with OData
const activeAccounts = await WebApiClient.Retrieve({
    entityName: "account",
    queryParams: "?$select=name,revenue&$filter=statecode eq 0&$orderby=name",
    returnAllPages: true
});

// Retrieve with FetchXML
const accountsWithContacts = await WebApiClient.Retrieve({
    entityName: "account",
    fetchXml: `
        <fetch mapping='logical' count='10'>
            <entity name='account'>
                <attribute name='name'/>
                <attribute name='telephone1'/>
                <link-entity name='contact' from='parentcustomerid' to='accountid'>
                    <attribute name='fullname'/>
                    <attribute name='emailaddress1'/>
                </link-entity>
            </entity>
        </fetch>`
});

// Retrieve with expanded collection properties
const accountsWithContacts = await WebApiClient.Retrieve({
    entityName: "account",
    queryParams: "?$expand=contact_customer_accounts($select=fullname,emailaddress1)"
});

// Handle expanded results
console.log("Accounts with contacts:", accountsWithContacts.value);

/**
 * Update an existing record
 * @param parameters - Update operation parameters
 * @returns Promise resolving to update confirmation or updated record
 */
function Update(parameters: UpdateParameters): Promise<string> | Promise<any> | string | any | BatchRequest;

interface UpdateParameters extends BaseParameters {
    /** Entity logical name */
    entityName?: string;
    /** Override for non-standard entity set names */
    overriddenSetName?: string;
    /** Record GUID to update */
    entityId?: string;
    /** Data object containing field values to update */
    entity: object;
    /** Alternate key criteria for identifying record to update */
    alternateKey?: Array<Key>;
}

// Basic update by ID
await WebApiClient.Update({
    entityName: "account",
    entityId: "12345678-1234-1234-1234-123456789abc",
    entity: {
        name: "Updated Account Name",
        telephone1: "555-9999"
    }
});

// Update by alternate key
await WebApiClient.Update({
    entityName: "contact",
    alternateKey: [
        { property: "emailaddress1", value: "john.doe@contoso.com" }
    ],
    entity: { lastname: "Smith" }
});

// Update with return representation
const updatedAccount = await WebApiClient.Update({
    entityName: "account",
    entityId: accountId,
    entity: { name: "New Name" },
    headers: [{ key: "Prefer", value: "return=representation" }]
});

// Clear a lookup field (use Delete operation for lookups)
await WebApiClient.Delete({
    entityName: "account",
    entityId: accountId,
    queryParams: "/primarycontactid/$ref"
});

// Upsert operation (update if exists, create if not)
await WebApiClient.Update({
    entityName: "contact",
    alternateKey: [
        { property: "emailaddress1", value: "new.contact@contoso.com" }
    ],
    entity: { firstname: "Jane", lastname: "Doe" }
    // Note: This is upsert by default with alternate key
});

/**
 * Delete a record or clear a field property
 * @param parameters - Delete operation parameters
 * @returns Promise resolving to delete confirmation
 */
function Delete(parameters: DeleteParameters): Promise<string> | string | BatchRequest;

interface DeleteParameters extends BaseParameters {
    /** Entity logical name */
    entityName?: string;
    /** Override for non-standard entity set names */
    overriddenSetName?: string;
    /** Record GUID to delete */
    entityId?: string;
    /** Alternate key criteria for identifying record to delete */
    alternateKey?: Array<Key>;
    /** Query parameters for field deletion (e.g., "/fieldname" or "/lookupfield/$ref") */
    queryParams?: string;
}

// Delete by ID
await WebApiClient.Delete({
    entityName: "account",
    entityId: "12345678-1234-1234-1234-123456789abc"
});

// Delete by alternate key
await WebApiClient.Delete({
    entityName: "contact",
    alternateKey: [
        { property: "emailaddress1", value: "obsolete.contact@contoso.com" }
    ]
});

// Clear a regular field
await WebApiClient.Delete({
    entityName: "account",
    entityId: accountId,
    queryParams: "/telephone1"
});

// Clear a lookup field
await WebApiClient.Delete({
    entityName: "account",
    entityId: accountId,
    queryParams: "/primarycontactid/$ref"
});

// Retrieve with collection expansion
const accountsWithContacts = await WebApiClient.Retrieve({
    entityName: "account",
    queryParams: "?$select=name&$expand=contact_customer_accounts($select=fullname,emailaddress1)"
});

// Process expanded collections
for (const account of accountsWithContacts.value) {
    console.log(`Account: ${account.name}`);
    if (account.contact_customer_accounts) {
        for (const contact of account.contact_customer_accounts) {
            console.log(`- Contact: ${contact.fullname} (${contact.emailaddress1})`);
        }
    }
}

/** Override global pagination behavior */
let ReturnAllPages: boolean;

// Enable automatic pagination for all retrieve operations
WebApiClient.ReturnAllPages = true;

// Configure multiple settings
WebApiClient.ReturnAllPages = true;
WebApiClient.ApiVersion = "9.0";
WebApiClient.PrettifyErrors = false;