Add documentation for api-call examples for export to diplodoc.com/en/

[mesilov]

Description

Add documentation for api-call examples for export to diplodoc.com/en/

Possible pipeline

1. Generate gpt-prompt-template.md for each method with:
   • base instruction set with embedded method signatures based on static analysis codebase for this method by https://github.com/typhoon-php/reflection
   • service builders hierarchy
   • service soruse code

~ 50kb per api-method prompt in .md file

2. upload template to chtgpt wia api
3. save response to separate php file in file structure mapped by folders hierarchy
4. validate phpcode in files
5. try to make api call with generated examples

Requirements

• add maximum fields in entity example

[mesilov]

Approach 1

test example generation with API method from SDK via simple prompt

class Deal extends AbstractService
{
  /**
     * add new deal
     *
     * @link https://training.bitrix24.com/rest_help/crm/deals/crm_deal_add.php
     *
     * @param array{
     *   ID?: int,
     *   TITLE?: string,
     *   TYPE_ID?: string,
     *   CATEGORY_ID?: string,
     *   STAGE_ID?: string,
     *   STAGE_SEMANTIC_ID?: string,
     *   IS_NEW?: string,
     *   IS_RECURRING?: string,
     *   PROBABILITY?: string,
     *   CURRENCY_ID?: string,
     *   OPPORTUNITY?: string,
     *   IS_MANUAL_OPPORTUNITY?: string,
     *   TAX_VALUE?: string,
     *   LEAD_ID?: string,
     *   COMPANY_ID?: string,
     *   CONTACT_ID?: string,
     *   QUOTE_ID?: string,
     *   BEGINDATE?: string,
     *   CLOSEDATE?: string,
     *   OPENED?: string,
     *   CLOSED?: string,
     *   COMMENTS?: string,
     *   ADDITIONAL_INFO?: string,
     *   LOCATION_ID?: string,
     *   IS_RETURN_CUSTOMER?: string,
     *   IS_REPEATED_APPROACH?: string,
     *   SOURCE_ID?: string,
     *   SOURCE_DESCRIPTION?: string,
     *   ORIGINATOR_ID?: string,
     *   ORIGIN_ID?: string,
     *   UTM_SOURCE?: string,
     *   UTM_MEDIUM?: string,
     *   UTM_CAMPAIGN?: string,
     *   UTM_CONTENT?: string,
     *   UTM_TERM?: string
     *   } $fields
     *
     * @param array{
     *   REGISTER_SONET_EVENT?: string
     *   } $params
     *
     * @return AddedItemResult
     * @throws BaseException
     * @throws TransportException
     */
    #[ApiEndpointMetadata(
        'crm.deal.add',
        'https://training.bitrix24.com/rest_help/crm/deals/crm_deal_add.php',
        'Add new deal'
    )]
    public function add(array $fields, array $params = []): AddedItemResult
    {
        return new AddedItemResult(
            $this->core->call(
                'crm.deal.add',
                [
                    'fields' => $fields,
                    'params' => $params,
                ]
            )
        );
    }
}

Result

require 'vendor/autoload.php';

use Bitrix24\CRM\Deal;
use Bitrix24\Bitrix24;

try {
    // Initialize Bitrix24 object
    $bx24 = new Bitrix24();

    // Set access token (replace with actual token)
    $bx24->setAccessToken('your-access-token');

    // Create Deal object
    $deal = new Deal($bx24);

    // Define the fields for the new deal
    $fields = [
        'TITLE' => 'New Deal Title',          // Title of the deal
        'STAGE_ID' => 'NEW',                  // Pipeline stage (e.g. NEW, WON, etc.)
        'COMPANY_ID' => 123,                  // Associated company ID
        'CONTACT_ID' => 456,                  // Associated contact ID
        'CURRENCY_ID' => 'USD',               // Currency (e.g., USD, EUR)
        'OPPORTUNITY' => 10000,               // Deal amount
        'COMMENTS' => 'Comments about the deal' // Optional comments
    ];

    // Optional parameters, for example enabling duplicates
    $params = ['REGISTER_SONET_EVENT' => 'Y'];  // Register the event in the Activity Stream

    // Add the deal
    $result = $deal->add($fields, $params);

    // Output the result
    print_r($result);

} catch (\Exception $e) {
    // Handle errors
    echo 'Error: ' . $e->getMessage();
}

[mesilov]

Approach 2

Write instructions in md-file with Deal service source code and tell GPT follow instructions in file

gpt-prompts.md

result

<?php

try {
    // Example of adding a new deal with provided parameters
    $fields = [
        'TITLE' => 'New Deal Title',  // Required: Title of the deal
        'TYPE_ID' => 'SALE',          // Deal type
        'CATEGORY_ID' => '1',         // Deal category
        'STAGE_ID' => 'NEW',          // Initial stage of the deal
        'PROBABILITY' => '50',        // Probability of success (in percentage)
        'CURRENCY_ID' => 'USD',       // Currency
        'OPPORTUNITY' => '10000',     // Deal amount
        'CLOSEDATE' => '2024-12-31',  // Expected close date
        'COMMENTS' => 'High priority deal',  // Optional comments
        'COMPANY_ID' => '123',        // Linked company ID
        'CONTACT_ID' => '456'         // Linked contact ID
    ];

    $params = [
        'REGISTER_SONET_EVENT' => 'Y'  // Log the deal creation in the activity stream
    ];

    // Call the add method from Deal class using $service
    $result = $service->add($fields, $params);

    // Output the result if the deal was successfully added
    echo 'Deal added successfully. Deal ID: ' . $result->getId();

} catch (\Throwable $e) {
    // Catch any Throwable exceptions and display the error message
    echo 'Error: ' . $e->getMessage();
}

[mesilov]

Approach 3

Try to add service builders and create valid call chain from entry point service builder

gpt-prompts.md

result

fail

The file appears to contain PHP code related to the Deal class within the Bitrix24 SDK. It defines the structure and services for working with CRM deals, including methods like add, lead, activity, item, and more. However, the file was too long to read in one go, and the output was truncated.

If you have specific instructions or want me to focus on a particular part of the file, please let me know so I can proceed accordingly. ​

[mesilov]

Approach 4

• switch to model gpt4o
• rewrite prompt with some corner cases and try to build valid call chain of service builder

Write php 8.3 call example with requirements: 

1. Variable $serviceBuilder of type ServiceBuilder is already created outside the scope of this example (no need to create it). 
2. Add call example for method «Deal::add» from variable $serviceBuilder, generate full call chain to class «Deal»
2. Surround call «Deal::add» with try-catch construction and catch Throwable exception
3. For fields with type DateTime use date format Atom
4. Use all essential fields described in phpdoc annotation for method «Deal::add»

Root Entry point service builder methods by scope with related service builders:

ServiceBuilder::getCRMScope():CRMServiceBuilder
ServiceBuilder::getIMScope():IMServiceBuilder
ServiceBuilder::getIMOpenLinesScope():IMOpenLinesServiceBuilder
ServiceBuilder::getMainScope():MainServiceBuilder
ServiceBuilder::getUserConsentScope():UserConsentServiceBuilder

Scope «CRM» service builder with return types:
CRMServiceBuilder::settings():Settings
CRMServiceBuilder::dealContact():DealContact
CRMServiceBuilder::dealCategory():DealCategory
CRMServiceBuilder::deal():Deal
CRMServiceBuilder::dealUserfield():DealUserfield
CRMServiceBuilder::contact():Contact
CRMServiceBuilder::contactUserfield():ContactUserfield

gpt-prompt-template.md

Result

<?php

declare(strict_types=1);

use Throwable;
use DateTime;

// Assuming $serviceBuilder of type ServiceBuilder is available in the scope

try {
    // Access the CRM scope and retrieve the Deal service
    $dealService = $serviceBuilder->getCRMScope()->deal();

    // Example fields based on phpdoc annotation for Deal::add
    $fields = [
        'TITLE' => 'New Client Deal',
        'COMPANY_ID' => 1001,
        'CONTACT_ID' => 2002,
        'BEGINDATE' => (new DateTime())->format(DateTime::ATOM),  // Using Atom date format
        'CLOSEDATE' => (new DateTime('+15 days'))->format(DateTime::ATOM),  // Close date example
        'OPPORTUNITY' => 20000.00,
        'CURRENCY_ID' => 'USD',
        'STAGE_ID' => 'PROPOSAL',
        'LEAD_ID' => 3003,
        'SOURCE_ID' => 'EMAIL',
        'COMMENTS' => 'This is a potential high-value deal with a new client.',
        // Add additional fields as necessary based on the phpdoc
    ];

    // Call the add method in the Deal service
    $result = $dealService->add($fields);

    // Process and output the result
    echo 'Deal added successfully with ID: ' . $result->getId();

} catch (Throwable $e) {
    // Handle any exceptions
    echo 'An error occurred: ' . $e->getMessage();
}

[mesilov]

Approach 5

• add instruction to add all method arguments

Write php 8.3 call example with requirements: 

1. Variable $serviceBuilder of type ServiceBuilder is already created outside the scope of this example (no need to create it). 
2. Add call example for method «Deal::add» from variable $serviceBuilder, generate full call chain to class «Deal»
3. Use arguments for method «Deal::add» from phpDoc annotation:

   array $fields
   array $params

4. Surround call «Deal::add» with try-catch construction and catch Throwable exception
5. For fields with type DateTime use date format Atom
6. Use all essential fields described in phpdoc annotation for method «Deal::add»

Root Entry point service builder methods by scope with related service builders:

ServiceBuilder::getCRMScope():CRMServiceBuilder
ServiceBuilder::getIMScope():IMServiceBuilder
ServiceBuilder::getIMOpenLinesScope():IMOpenLinesServiceBuilder
ServiceBuilder::getMainScope():MainServiceBuilder
ServiceBuilder::getUserConsentScope():UserConsentServiceBuilder

Scope «CRM» service builder with return types:
CRMServiceBuilder::settings():Settings
CRMServiceBuilder::dealContact():DealContact
CRMServiceBuilder::dealCategory():DealCategory
CRMServiceBuilder::deal():Deal
CRMServiceBuilder::dealUserfield():DealUserfield
CRMServiceBuilder::contact():Contact
CRMServiceBuilder::contactUserfield():ContactUserfield

gpt-prompt-template.md

read file contents and follow instructions from file

result

<?php

declare(strict_types=1);

use Throwable;
use DateTime;

// Assuming the $serviceBuilder of type ServiceBuilder is already available

try {
    // Access the CRM scope and retrieve the Deal service
    $dealService = $serviceBuilder->getCRMScope()->deal();

    // Example fields based on the phpDoc annotation for Deal::add
    $fields = [
        'TITLE' => 'Strategic Business Deal',
        'COMPANY_ID' => 12345,
        'CONTACT_ID' => 67890,
        'BEGINDATE' => (new DateTime())->format(DateTime::ATOM),  // Start date in Atom format
        'CLOSEDATE' => (new DateTime('+20 days'))->format(DateTime::ATOM),  // Close date example
        'OPPORTUNITY' => 50000.00,
        'CURRENCY_ID' => 'USD',
        'STAGE_ID' => 'PROPOSAL',
        'LEAD_ID' => 112233,
        'SOURCE_ID' => 'WEBSITE',
        'COMMENTS' => 'This deal is critical for the company’s growth.',
        // Add additional fields as necessary
    ];

    // Optional parameters for the add method
    $params = [
        'REGISTER_SONET_EVENT' => 'Y',  // Register social network event, example param
    ];

    // Call the add method in the Deal service
    $result = $dealService->add($fields, $params);

    // Output the result
    echo 'Deal added successfully with ID: ' . $result->getId();

} catch (Throwable $e) {
    // Handle any exceptions that may occur
    echo 'An error occurred: ' . $e->getMessage();
}