### Example: Bonus Master Start Date Before Term Start

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoKeisanPatternDataService

Demonstrates a case where the bonus master's start date precedes the beginning of the term. This scenario is relevant when the bonus item was effective before the current calculation term.

```typescript
賞与基本マスタのstartDateが期間の開始日より前の場合
// 期間: 2022/4/1～2023/3/31
// 賞与基本マスタ: startDate=2022/3/1
// 賞与計算パターン: 対象項目を含む
// => '2022/4/1' を返す

```

--------------------------------

### Example: Bonus Master Start Date After Term Start (Mid-Year Hire)

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoKeisanPatternDataService

Shows the scenario where the bonus master's start date is after the term begins, simulating a mid-year hire. The returned date will be based on the employee's hiring date if it falls within the term and is after the term's start.

```typescript
賞与基本マスタのstartDateが期間の開始日より後の場合（算定期間中入社の場合）
// 期間: 2022/4/1～2023/3/31
// 賞与基本マスタ: startDate=2022/6/1
// 賞与計算パターン: 対象項目を含む
// => '2022/6/1' を返す（入社日が基準日として取得される）

```

--------------------------------

### Example: Bonus Calculation Pattern Throughout the Term

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoKeisanPatternDataService

Illustrates a scenario where the bonus calculation pattern, including the target bonus item, is present for the entire term. This example shows the expected return value when the bonus master's start date aligns with the term's start date.

```typescript
算定期間中ずっと対象の賞与項目を含む賞与計算パターンの場合
// 期間: 2022/4/1～2023/3/31
// 賞与基本マスタ: startDate=2022/4/1
// 賞与計算パターン: 対象項目を含む
// => '2022/4/1' を返す

```

--------------------------------

### Example: Salary master start date after the term begins

Source: https://wiki.combosite-func.jp/api/classes/CombositeKeisanPatternDataService

Demonstrates a situation where the salary master's start date falls after the beginning of the term. The returned date will be the salary master's start date, provided the salary item is in the pattern.

```typescript
給与基本マスタのstartDateが期間の開始日より後の場合
// 期間: 2025/01/01～2025/01/31
// 給与基本マスタ: startDate=2025/01/20
// 計算パターン: 対象項目を含む
// => '2025/01/20' を返す

```

--------------------------------

### Example: Salary master start date before the term begins

Source: https://wiki.combosite-func.jp/api/classes/CombositeKeisanPatternDataService

Shows the case where the salary master's start date precedes the beginning of the specified term. The method returns the term's start date if the salary item is present in the pattern.

```typescript
給与基本マスタのstartDateが期間の開始日より前の場合
// 期間: 2025/01/01～2025/01/31
// 給与基本マスタ: startDate=2024/12/01
// 計算パターン: 対象項目を含む
// => '2025/01/01' を返す

```

--------------------------------

### Example: Bonus Master Start Date Outside Term

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoKeisanPatternDataService

Shows a scenario where the bonus master's start date falls outside the specified term. This indicates that the bonus item was not applicable during the term, and the method returns null.

```typescript
賞与基本マスタのstartDateが期間外の場合
// 期間: 2022/4/1～2023/3/31
// 賞与基本マスタ: startDate=2023/4/1
// => null を返す

```

--------------------------------

### Example Usage of read()

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoShiwakeDataService

Demonstrates how to call the `read` method on `combositeDataService.shoyoShiwakeData` to obtain bonus journal source data. Ensure the service instance is already provided.

```javascript
async function main() {
  const response = await combositeDataService.shoyoShiwakeData.read()
}

main()
```

--------------------------------

### Example Usage of CombositeShiwakeDataService.read

Source: https://wiki.combosite-func.jp/api/classes/CombositeShiwakeDataService

Demonstrates how to call the `read` method of the `combositeDataService.shiwakeData` to fetch payroll journal source data. Ensure the service instance is already initialized.

```javascript
async function main() {
  const response = await combositeDataService.shiwakeData.read()
}

main()
```

--------------------------------

### Example: Salary item present throughout the calculation period

Source: https://wiki.combosite-func.jp/api/classes/CombositeKeisanPatternDataService

Illustrates a scenario where the salary item is included in the calculation pattern for the entire duration of the term. The returned date is the start date of the salary master.

```typescript
計算期間中ずっと対象の給与項目を含む計算パターンの場合
// 期間: 2025/01/01～2025/01/31
// 給与基本マスタ: startDate=2025/01/01
// 計算パターン: 対象項目を含む
// => '2025/01/01' を返す

```

--------------------------------

### Response Example for read()

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoShiwakeDataService

Illustrates the structure of the response received from the `read` method, showing an array of `ShiwakeDataEntity` objects, each containing details about bonus payments.

```json
{
  "shiwakeData": [
    {
      "shiharaiName": "賞与支払い_正社員",
      "corpName": "パトスロゴス",
      "shozokuGenkaCode": "10001",
      "hatsureiGenkaCode": "AZ0001",
      "jigyoshoName": "A事業所",
      "keiriKomokuName": "人件費",
      "yakushokuName": "主任",
      "shokuiName": "主任",
      "shokunoShikakuName": "監督職能",
      "shokushuName": "営業",
      "koyoKeitaiName": "正社員",
      "shokugunName": "総合職",
      "rankName": null,
      "futanCorpName": "A会社",
      "shainId": null,
      "shainName": null,
      "amount": 100000
    }
  ]
}
```

--------------------------------

### Custom Function Implementation Example (JavaScript)

Source: https://wiki.combosite-func.jp/

This JavaScript code demonstrates how to implement a custom function in BaaS. It shows how to use the `combositeDataService` to read data and defines a main function to be executed. The `combositeDataService` usage depends on the selected execution trigger.

```javascript
async function main() {

  const response = await combositeDataService.shiwakeData.read()

}


function sub() {

  // 何らかの処理

}


main()
```

--------------------------------

### Example: Salary master start date outside the term

Source: https://wiki.combosite-func.jp/api/classes/CombositeKeisanPatternDataService

Demonstrates a scenario where the salary master's start date falls completely outside the specified term. The method returns null as the item is not relevant within the given period.

```typescript
給与基本マスタのstartDateが期間外の場合
// 期間: 2025/01/01～2025/01/31
// 給与基本マスタ: startDate=2025/02/01
// => null を返す

```

--------------------------------

### Download File (curl)

Source: https://wiki.combosite-func.jp/wiki/custom-storage/external-file-api

Use this command to download a file using the signed URL obtained from the API. The `method` in the response should be `GET`.

```bash
curl -i -X GET "<レスポンスの url>"
```

--------------------------------

### Example Usage of saveAmount

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoShikyukojoDataService

Demonstrates how to use the `saveAmount` method to update bonus payment and deduction amounts. Ensure that the `baseDate` is correctly set for each entry.

```javascript
async function main() {
  const koteiShikyukojoList = [
    {
      employeeId: '100000',
      shoyoKomokuName: '固定支給',
      amount: 50000,
      baseDate: '2025/4/1', // 更新対象のデータの基準日
    },
    {
      employeeId: '100001',
      shoyoKomokuName: '固定控除',
      amount: 10000,
      baseDate: '2025/4/1', // 更新対象のデータの基準日
    }
  ]
  await combositeDataService.shoyoShikyukojoData.saveAmount(koteiShikyukojoList)
}
main()
```

--------------------------------

### Example: Calculation pattern changes within the term

Source: https://wiki.combosite-func.jp/api/classes/CombositeKeisanPatternDataService

Illustrates a scenario where the calculation pattern changes during the term, and the target salary item is only present in the later pattern. The method returns the start date of the period with the target item.

```typescript
期間中に計算パターンが切り替わり、切り替え後のパターンにのみ対象項目が存在する場合
// 期間: 2025/01/01～2025/01/31
// 給与基本マスタ: [startDate=2025/01/01, パターンA(対象項目なし)], [startDate=2025/01/15, パターンB(対象項目あり)]
// => '2025/01/15' を返す

```

--------------------------------

### Example: Bonus Pattern Changes Mid-Term

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoKeisanPatternDataService

Illustrates a situation where the bonus calculation pattern changes during the term, and the target bonus item is only present in the later pattern. The method returns the start date of the pattern that includes the bonus item.

```typescript
期間中に賞与計算パターンが切り替わり、切り替え後のパターンにのみ対象項目が存在する場合
// 期間: 2022/4/1～2023/3/31
// 賞与基本マスタ: [startDate=2022/4/1, パターンA(対象項目なし)], [startDate=2022/6/1, パターンB(対象項目あり)]
// => '2022/6/1' を返す

```

--------------------------------

### Access Token Response (JSON)

Source: https://wiki.combosite-func.jp/external-api

This is an example of a successful JSON response when requesting an access token. It includes the token itself, its type, and its expiration time.

```JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

--------------------------------

### Get First Date by Term and Bonus Item Name

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoKeisanPatternDataService

Retrieves the first date an employee is associated with a specific bonus item within a given term. Use this method when you need to find the start date of a bonus item's applicability for an employee within a defined period. The service instance is already provided, so access it via `combositeDataService.shoyoKeisanPatternData`.

```typescript
getFirstDateByTermAndShoyoKomokuName(
   employeeId,
   shoyoKomokuName,
term): Promise<string | null>;

```

--------------------------------

### Response Example for read()

Source: https://wiki.combosite-func.jp/api/classes/CombositeShiwakeDataService

Illustrates the structure of the response when retrieving payroll journal source data. The response contains an array of `shiwakeData` entities, each with various details about the payment and associated company information.

```json
{
  "shiwakeData": [
    {
      "shiharaiName": "25日払い_正社員",
      "corpName": "パトスロゴス",
      "shozokuGenkaCode": "10001",
      "hatsureiGenkaCode": "AZ0001",
      "jigyoshoName": "A事業所",
      "keiriKomokuName": "人件費",
      "yakushokuName": "主任",
      "shokuiName": "主任",
      "shokunoShikakuName": "監督職能",
      "shokushuName": "営業",
      "koyoKeitaiName": "正社員",
      "shokugunName": "総合職",
      "rankName": null,
      "futanCorpName": "A会社",
      "shainId": null,
      "shainName": null,
      "amount": 100000
    }
  ]
}
```

--------------------------------

### Custom Function Implementation for Scheduler

Source: https://wiki.combosite-func.jp/wiki/custom-data-function/custom-function-scheduler

Implement your custom function logic within the main async function. This example logs a message indicating successful scheduler execution and provides a placeholder for your custom logic.

```javascript
async function main() {
  logger.info('スケジューラー実行完了!')
  // 定期実行で実行したい処理を記述
}

main()
```

--------------------------------

### Example: No Applicable Bonus Pattern Found

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoKeisanPatternDataService

Demonstrates the case where no bonus calculation pattern containing the target bonus item exists within the specified term. The method returns null in this scenario.

```typescript
期間中に対象の賞与項目を含む賞与計算パターンが存在しない場合
// 期間: 2022/4/1～2023/3/31
// 賞与基本マスタ: startDate=2022/4/1
// 賞与計算パターン: 対象項目なし
// => null を返す

```

--------------------------------

### Example: Target salary item not found in any pattern within the term

Source: https://wiki.combosite-func.jp/api/classes/CombositeKeisanPatternDataService

Shows the case where no calculation pattern within the specified term includes the target salary item. The method returns null in this situation.

```typescript
期間中に対象の給与項目を含む計算パターンが存在しない場合
// 期間: 2025/01/01～2025/01/31
// 給与基本マスタ: startDate=2025/01/01
// 計算パターン: 対象項目なし
// => null を返す

```

--------------------------------

### Get Access Token (Shell Curl)

Source: https://wiki.combosite-func.jp/external-api

Use this cURL command to obtain an access token for external API access. Ensure you replace 'username:password' with your actual Client ID and Client Secret.

```Shell
curl https://functions.combosite-func.jp/auth-getaccesstoken \
  --request POST \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic username:password' \
  --data-urlencode 'grant_type=client_credentials'
```

--------------------------------

### KyosoGraphQLClient Instantiation

Source: https://wiki.combosite-func.jp/api/classes/KyosoGraphQLClient

Instantiate the KyosoGraphQLClient with your credentials and base URL.

```APIDOC
## KyosoGraphQLClient Constructor

### Description
Instantiate the KyosoGraphQLClient with your credentials and base URL.

### Parameters
#### Request Body
- **clientId** (string) - Required - Your client ID.
- **clientSecret** (string) - Required - Your client secret.
- **baseUrl** (string) - Required - The base URL of the Kyoso GraphQL API.
- **apiKey** (string) - Required - Your API key.
```

--------------------------------

### Instantiate KyosoGraphQLClient

Source: https://wiki.combosite-func.jp/api/classes/KyosoGraphQLClient

Instantiate the KyosoGraphQLClient with your API credentials and base URL. Ensure you replace placeholder values with your actual credentials.

```typescript
const client = new KyosoGraphQLClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  baseUrl: 'https://api.kyoso.com',
  apiKey: 'your-api-key',
})
```

--------------------------------

### Basic Custom Function JavaScript

Source: https://wiki.combosite-func.jp/tutorial/tutorial-advanced/register-custom-functions-base

This is a basic JavaScript function that logs 'hello world' to the console using the Combosite logger. Ensure all custom logic is placed within the `main` function.

```javascript
async function main() {
  logger.info('hello world')
}

main()
```

--------------------------------

### Get Salary Calculation Base Date

Source: https://wiki.combosite-func.jp/api/classes/CombositeKyuyoKeisanSettingsDataService

Retrieves the base date for salary calculations. Use this to get a specific day within the calculation period or the last day of the month.

```typescript
getKeisanKikanBaseDate(baseDate): Promise<string>;
```

```javascript
async function main() {
  // 基準日が15日の場合の日付を取得
  const baseDate = await combositeDataService.kyuyoKeisanSettingsData.getKeisanKikanBaseDate(15)
  logger.info(baseDate) // '2025/04/15'

  // 基準日が月末(99)の場合の日付を取得
  const lastDayBaseDate = await combositeDataService.kyuyoKeisanSettingsData.getKeisanKikanBaseDate(99)
  logger.info(lastDayBaseDate) // '2025/04/30'
}
main()
```

--------------------------------

### Getting Discriminant Value Name in Custom Function

Source: https://wiki.combosite-func.jp/wiki/custom-data-function/enum

Retrieve the name of a discriminant value from fetched発令 (hatsurei) data using the corresponding 'get{DiscriminantName}Name' function. Ensure 'entity' is imported.

```javascript
// 取得した発令データ.在籍状況区分の在籍状況区分値名称を取得する
const zaisekiJokyoKubunName = entity.getZaisekiJokyoKubunName(
  targetHatsureiData.zaisekiJokyoKubun
)
```

--------------------------------

### Execute GET Request with HttpRequest

Source: https://wiki.combosite-func.jp/api/classes/HttpRequest

Use this snippet to perform a GET request to a specified URL using the httpRequest instance. Ensure the URL uses http or https and is not a local or private IP address.

```typescript
// GETリクエスト
const response = await httpRequest.execute('https://api.example.com/data', { method: 'GET' })
console.log(response.data)
```

--------------------------------

### Get Bonus Calculation Base Date

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoKeisanSettingsDataService

Retrieves the base date for bonus calculation periods. Use this to get specific dates based on the period end date, or special values for month-end or closing dates. Note: This method cannot be used during test execution.

```javascript
async function main() {
  // 基準日が15日の場合の日付を取得
  const baseDate = await combositeDataService.shoyoKeisanSettingsData.getShoyoSanteiKikanBaseDate(15)
  logger.info(baseDate) // '2025/09/15'

  // 基準日が月末(99)の場合の日付を取得
  const lastDayBaseDate = await combositeDataService.shoyoKeisanSettingsData.getShoyoSanteiKikanBaseDate(99)
  logger.info(lastDayBaseDate) // '2025/09/30'

  // 基準日が締め日(100)の場合の日付を取得
  const shimeDate = await combositeDataService.shoyoKeisanSettingsData.getShoyoSanteiKikanBaseDate(100)
  logger.info(shimeDate) // '2025/09/30'
}
await main()
```

--------------------------------

### Term Properties

Source: https://wiki.combosite-func.jp/api/interfaces/Term

Represents a time period with start and end dates.

```APIDOC
## Term Object

### Description
Represents a time period.

### Properties
#### start (string) - Description: Start date (yyyy/MM/dd)
#### end (string) - Description: End date (yyyy/MM/dd)
```

--------------------------------

### KyosoGraphQLClient インスタンスの生成と GraphQL クエリ実行

Source: https://wiki.combosite-func.jp/wiki/custom-data-function/kyoso-graphql

共創 GraphQL API との連携に必要な `KyosoGraphQLClient` のインスタンスを生成し、ページネーションを伴うクエリを実行する例です。認証情報とクエリ、およびページネーションのための変数を設定します。

```typescript
const client = new KyosoGraphQLClient({
  clientId: 'KYOSO_CLIENT_ID',
  clientSecret: 'KYOSO_CLIENT_SECRET',
  baseUrl: 'KYOSO_BASE_URL',
  apiKey: 'KYOSO_API_KEY',
})

const query = "
    query ListShainJoho($input: ShainJohoSearchInput, $first: Int, $after: String) {
        listShainJoho(input: $input, first: $first, after: $after) {
            totalCount
            pageInfo {
                endCursor
                hasNextPage
            }
            edges {
                node {
                    id
                    shainId
                }
            }
        }
    }
"
try {
  const firstPage = await client.execute({
    query,
    variables: {
      input: null,
      first: 10,
    },
  })
  const nextPage = await client.execute({
    query,
    variables: {
      input: null,
      first: 10,
      after: firstPage.data?.listShainJoho?.pageInfo?.endCursor,
    },
  })
} catch (error) {
  logger.error('エラーが発生しました', { error })
}
```

--------------------------------

### KyosoGraphQLClient

Source: https://wiki.combosite-func.jp/api

Kyoso GraphQL class. Please instantiate and use.

```APIDOC
## KyosoGraphQLClient

### Description
Kyoso GraphQL class. Please instantiate and use.

### Service
KyosoGraphQLClient
```

--------------------------------

### Get a List of All Custom Secrets

Source: https://wiki.combosite-func.jp/api/classes/UserCustomSecretsManager

Use `getSecretList` to fetch all available custom secrets. This method returns an array of custom secret objects.

```typescript
const secretList = await customSecretsManager.getSecretList()
logger.info('カスタムシークレット一覧を取得しました', { secretList }) // [{ name: 'your-secret-name', secret: 'your-secret-value' },{ name: 'your-secret-name2', secret: 'your-secret-value2' }]
```

--------------------------------

### Get a Custom Secret by Name

Source: https://wiki.combosite-func.jp/api/classes/UserCustomSecretsManager

Use `getSecretByName` to retrieve a specific custom secret using its name. Ensure you have the correct secret name.

```typescript
const secret = await customSecretsManager.getSecretByName('your-secret-name')
logger.info('カスタムシークレットを取得しました', { secret }) // { name: 'your-secret-name', secret: 'your-secret-value' }
```

--------------------------------

### カスタムデータサービスの取得

Source: https://wiki.combosite-func.jp/wiki/custom-data-function/custom-data-for-custom-function

カスタムデータにアクセスするために、baseServiceを使用してカスタムデータサービスのインスタンスを取得します。カスタムデータ定義名（テーブル名）を指定してサービスインスタンスを取得してください。

```typescript
const customDataService =
  await baseService.createCustomDataServiceByDefinitionName(
    'カスタムデータ定義名'
  )
```

--------------------------------

### Get Custom Data by Query

Source: https://wiki.combosite-func.jp/api/classes/UserCustomDataService

Retrieve custom data entries based on specified query conditions. This method supports various comparison operators for filtering data.

```typescript
// 例としてカスタムデータ定義名からカスタムデータサービスを作成する
// ※ペット手当マスタというカスタムデータ定義名のカスタムデータを取得する
const service = await baseService.createCustomDataServiceByDefinitionName('ペット手当マスタ')

// amountが1000のカスタムデータを取得する
const customData = await service.getCustomDataByQuery(qb => qb.where('amount', '==', 1000))
```

```typescript
// amountが2000以上のカスタムデータを取得する
const customData = await service.getCustomDataByQuery(qb => qb.where('amount', '>=', 2000))
```

```typescript
// petTypeがdogまたはcatのカスタムデータを取得する
const customData = await service.getCustomDataByQuery(qb => qb.where('petType', 'in', ['dog', 'cat']))
```

```typescript
// petTypeがdogでもcatでもないカスタムデータを取得する
const customData = await service.getCustomDataByQuery(qb => qb.where('petType', 'not-in', ['dog', 'cat']))
```

```typescript
// amountが1000かつpetTypeがdogのカスタムデータを取得する
const customData = await service.getCustomDataByQuery(qb => qb.where('amount', '==', 1000).where('petType', '==', 'dog'))
```

```typescript
// NG例
const customData = await service.getCustomDataByQuery(qb => qb.where('amount', '>=', 1000).where('petType', '==', 'dog'))
```

--------------------------------

### execute()

Source: https://wiki.combosite-func.jp/api/classes/HttpRequest

Executes an HTTP request to a specified URL with given options. It returns a Promise that resolves with the AxiosResponse.

```APIDOC
## execute()

### Description
Executes an HTTP request to a specified URL with given options. It returns a Promise that resolves with the AxiosResponse.

### Method
execute

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **url** (string) - Required - The URL to which the request will be sent.
- **options** (HttpRequestOptions) - Required - The request options, including method and data.

### Request Example
```typescript
// GET request
const response = await httpRequest.execute('https://api.example.com/data', { method: 'GET' })
console.log(response.data)

// POST request
const postResponse = await httpRequest.execute('https://api.example.com/data', { method: 'POST', data: { name: 'John', age: 30 } })
console.log(postResponse.data)
```

### Response
#### Success Response (200)
- **data** (any) - The data returned in the response.

#### Response Example
```json
{
  "data": "response data"
}
```
```

--------------------------------

### CombositeShoyoKeisanSettingsDataService

Source: https://wiki.combosite-func.jp/api

Service to operate on bonus calculation settings data.

```APIDOC
## CombositeShoyoKeisanSettingsDataService

### Description
Operates on bonus calculation settings data.

### Class
CombositeShoyoKeisanSettingsDataService
```

--------------------------------

### CombositeKeisanPatternDataService

Source: https://wiki.combosite-func.jp/api

Service to retrieve calculation pattern data.

```APIDOC
## CombositeKeisanPatternDataService

### Description
Retrieves calculation pattern data.

### Class
CombositeKeisanPatternDataService
```

--------------------------------

### CombositeShoyoKeisanPatternDataService

Source: https://wiki.combosite-func.jp/api

Service to retrieve bonus calculation pattern data.

```APIDOC
## CombositeShoyoKeisanPatternDataService

### Description
Retrieves bonus calculation pattern data.

### Class
CombositeShoyoKeisanPatternDataService
```

--------------------------------

### getFirstDateByTermAndShoyoKomokuName

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoKeisanPatternDataService

Retrieves the first date when a specific bonus item is associated with a bonus calculation pattern within a given term. This is useful for determining the effective start date of a bonus item's inclusion in patterns.

```APIDOC
## getFirstDateByTermAndShoyoKomokuName

### Description
Retrieves the first date within a given term for which a specified bonus item is linked to a bonus calculation pattern. This method is crucial for understanding when a bonus item became active within the defined calculation periods.

### Method
`getFirstDateByTermAndShoyoKomokuName(employeeId: string, shoyoKomokuName: string, term: Term): Promise<string | null>`

### Parameters
#### Path Parameters
- **employeeId** (string) - Required - Employee ID.
- **shoyoKomokuName** (string) - Required - Bonus item name.
- **term** (Term) - Required - The target term (interface `Term` is referenced).

### Returns
`Promise<string | null>` - The first date (in YYYY/MM/DD format) when the bonus item is linked to a bonus calculation pattern. Returns `null` if no such date is found within the term or if the associated master data falls outside the term.

### Examples
```ts
// Example 1: Bonus item included throughout the calculation period
// Term: 2022/4/1 to 2023/3/31
// Bonus Master: startDate=2022/4/1
// Bonus Calculation Pattern: Includes the target item
// Result: '2022/4/1'

// Example 2: Bonus master startDate is before the term start date
// Term: 2022/4/1 to 2023/3/31
// Bonus Master: startDate=2022/3/1
// Bonus Calculation Pattern: Includes the target item
// Result: '2022/4/1'

// Example 3: Bonus master startDate is after the term start date (hiring date within term)
// Term: 2022/4/1 to 2023/3/31
// Bonus Master: startDate=2022/6/1
// Bonus Calculation Pattern: Includes the target item
// Result: '2022/6/1' (hiring date is used as the reference)

// Example 4: Bonus calculation pattern changes during the term, target item only in later pattern
// Term: 2022/4/1 to 2023/3/31
// Bonus Master: [startDate=2022/4/1, Pattern A (no target item)], [startDate=2022/6/1, Pattern B (target item present)]
// Result: '2022/6/1'

// Example 5: No bonus calculation pattern includes the target bonus item during the term
// Term: 2022/4/1 to 2023/3/31
// Bonus Master: startDate=2022/4/1
// Bonus Calculation Pattern: No target item
// Result: null

// Example 6: Bonus master startDate is outside the term
// Term: 2022/4/1 to 2023/3/31
// Bonus Master: startDate=2023/4/1
// Result: null
```
```

--------------------------------

### Custom Function Execution During Retrospective Calculation

Source: https://wiki.combosite-func.jp/wiki/frequently-asked-questions

This sample demonstrates how to access employee IDs and calculation settings within a custom function when performing retrospective calculations. It logs the processing month, start and end dates, and the number of employees to be calculated.

```javascript
async function main() {
  const employeeIdList = combositeDataService.shikyukojoData.employeeIdList
  const keisanEndDate =
    combositeDataService.kyuyoKeisanSettingsData.keisanEndDate
  const keisanStartDate =
    combositeDataService.kyuyoKeisanSettingsData.keisanStartDate
  const shoriNengetsu =
    combositeDataService.kyuyoKeisanSettingsData.shoriNengetsu

  logger.info(
    `処理年月: ${shoriNengetsu}の計算を実施: 計算開始日: ${keisanStartDate}, 計算終了日: ${keisanEndDate}`
  )
  logger.info(`計算対象者: ${employeeIdList.length}人, `, employeeIdList)
}

main()
```

--------------------------------

### カスタムデータの取得と更新

Source: https://wiki.combosite-func.jp/wiki/custom-data-function/custom-data-for-custom-function

カスタムデータ定義名 '共通データA' のデータを全件取得し、最初の1件を更新します。更新する項目のみを指定して updateCustomData メソッドを使用してください。更新前後のデータをログに出力して確認します。

```javascript
// カスタムデータを1件更新する
async function main() {
  // カスタムデータ定義名: `共通データA`のデータサービスを作成する
  const service =
    await baseService.createCustomDataServiceByDefinitionName('共通データA')

  // データを全件取得する
  const currentCustomData = await service.getCustomDataByQuery((qb) => qb)

  // デバッグ用に更新前のデータをログ出力する
  logger.info('更新前データ', currentCustomData)

  if (currentCustomData.length > 0) {
    // データを1件取得する
    const target = currentCustomData[0]

    // データのユニークIDを取得する
    const { docId } = target

    // 更新するデータを作成する(更新する項目のみ)
    const newData = {
      requiredString: 'hello world',
    }

    // データの更新処理を行う
    const result = await service.updateCustomData(docId, newData)
  }

  // 再度データを全件取得して更新が反映されているか確認する
  const updatedCustomData = await service.getCustomDataByQuery((qb) => qb)
  logger.info('更新後データ', updatedCustomData)
}

main()
```

--------------------------------

### Get Signed URL

Source: https://wiki.combosite-func.jp/wiki/custom-storage/external-file-api

Obtain a signed URL for file upload or download operations. This involves sending a request with an access token and specifying the action and file name. For uploads, additional parameters like contentType and overwrite may be required.

```APIDOC
## POST /auth/getstorageurl

### Description
Obtains a signed URL for uploading or downloading files from custom storage. The URL is valid for 15 minutes.

### Method
POST

### Endpoint
/auth/getstorageurl

### Parameters
#### Request Body
- **action** (string) - Required - The action to perform, either 'upload' or 'download'.
- **name** (string) - Required - The name of the file.
- **contentType** (string) - Optional - The content type of the file (required for uploads).
- **overwrite** (boolean) - Optional - Whether to allow overwriting an existing file (defaults to false, relevant for uploads).

### Request Example
```json
{
  "action": "upload",
  "name": "example.txt",
  "contentType": "text/plain",
  "overwrite": true
}
```

### Response
#### Success Response (200)
- **url** (string) - The signed URL for the file operation.
- **method** (string) - The HTTP method to use with the signed URL (e.g., PUT for upload, GET for download).
- **headers** (object) - Additional headers required for the request, such as `x-goog-if-generation-match` for conditional uploads.

#### Response Example
```json
{
  "url": "https://storage.googleapis.com/your-bucket/example.txt?Signature=...",
  "method": "PUT",
  "headers": {
    "x-goog-if-generation-match": "0"
  }
}
```
```

--------------------------------

### read()

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoShiwakeDataService

Retrieves the journal source data created during the Combosite 'Bonus Journal Source Data Output' process. It fetches only the journal source data related to the bonus payment master specified during the output process.

```APIDOC
## read()

### Description
Retrieves the journal source data created during the Combosite 'Bonus Journal Source Data Output' process. It fetches only the journal source data related to the bonus payment master specified during the output process.

### Method
GET

### Endpoint
/combosite/shoyoShiwakeData

### Parameters
This method does not accept any parameters.

### Response
#### Success Response (200)
- **shiwakeData** (ShiwakeDataEntity[]) - An array of journal source data entities.

#### Response Example
```json
{
  "shiwakeData": [
    {
      "shiharaiName": "賞与支払い_正社員",
      "corpName": "パトスロゴス",
      "shozokuGenkaCode": "10001",
      "hatsureiGenkaCode": "AZ0001",
      "jigyoshoName": "A事業所",
      "keiriKomokuName": "人件費",
      "yakushokuName": "主任",
      "shokuiName": "主任",
      "shokunoShikakuName": "監督職能",
      "shokushuName": "営業",
      "koyoKeitaiName": "正社員",
      "shokugunName": "総合職",
      "rankName": null,
      "futanCorpName": "A会社",
      "shainId": null,
      "shainName": null,
      "amount": 100000
    }
  ]
}
```

### Field Details
| **フィールド**        | **フィールド物理名** | **フィールド説明**                       | **フィールド形式** | 
| --------------------- | -------------------- | ---------------------------------------- | ------------------ | 
| 支払マスタ名称        | shiharaiName         | Combosite で管理している賞与支払マスタの名称 | string  | null    | 
| 会社名称              | corpName             | Combosite で管理している会社名称         | string  | null    | 
| 所属原価コード        | shozokuGenkaCode     | Combosite で管理している所属の原価コード | string  | null    | 
| 発令原価コード        | hatsureiGenkaCode    | Combosite で管理している発令の原価コード | string  | null    | 
| 事業所名称            | jigyoshoName         | Combosite で管理している事業所名称       | string  | null    | 
| 経理項目名称          | keiriKomokuName      | Combosite で管理している経理項目の名称   | string  | null    | 
| 役職名称              | yakushokuName        | Combosite で管理している役職の名称       | string  | null    | 
| 職位名称              | shokuiName           | Combosite で管理している職位の名称       | string  | null    | 
| 職能資格名称          | shokunoShikakuName   | Combosite で管理している職能資格の名称   | string  | null    | 
| 職種名称              | shokushuName         | Combosite で管理している職種の名称       | string  | null    | 
| 雇用形態名称          | koyoKeitaiName       | Combosite で管理している雇用形態の名称   | string  | null    | 
| 職群名称              | shokugunName         | Combosite で管理している職群の名称       | string  | null    | 
| ランク名称            | rankName             | Combosite で管理しているランクの名称     | string  | null    | 
| 負担会社名称          | futanCorpName        | Combosite で管理している負担会社の名称   | string  | null    | 
| 従業員 ID             | shainId              | Combosite で管理している従業員の ID      | string  | null    | 
| 従業員名称            | shainName            | Combosite で管理している従業員の名称     | string  | null    | 
| 金額                  | amount               | 当該仕訳元データの金額                   | number             | 

### Example
**Usage Example**
```js
async function main() {
  const response = await combositeDataService.shoyoShiwakeData.read()
}

main()
```
```

--------------------------------

### CombositeKyuyoKeisanSettingsDataService

Source: https://wiki.combosite-func.jp/api

Service to operate on payroll calculation settings data.

```APIDOC
## CombositeKyuyoKeisanSettingsDataService

### Description
Operates on payroll calculation settings data.

### Class
CombositeKyuyoKeisanSettingsDataService
```

--------------------------------

### Get First Date by Term and Salary Item Name

Source: https://wiki.combosite-func.jp/api/classes/CombositeKeisanPatternDataService

Retrieves the first date an employee's salary item is associated with within a specified term. Use this method when you need to find the earliest occurrence of a salary item's pattern within a given period.

```typescript
getFirstDateByTermAndKyuyoKomokuName(
   employeeId,
   kyuyoKomokuName,
term): Promise<string | null>;

```

--------------------------------

### CombositeShoyoShikyukojoDataService

Source: https://wiki.combosite-func.jp/api

Service to operate on bonus amount/deduction master data.

```APIDOC
## CombositeShoyoShikyukojoDataService

### Description
Operates on bonus amount/deduction master data.

### Class
CombositeShoyoShikyukojoDataService
```

--------------------------------

### Update Bonus Payment and Deduction Amounts

Source: https://wiki.combosite-func.jp/api/classes/CombositeShoyoShikyukojoDataService

Updates bonus payment and deduction master data amounts during the 'Pre-calculation Execution' and 'Main Calculation Execution' processes. Only data with 'Fixed Payment' or 'Fixed Deduction' as the bonus item category and 'Direct Amount Input' as the calculation method can be updated. Each bonus payment/deduction master data can only be updated once per employee per request. The specified base date is used as the start date for the master data to be updated. If the base date is earlier than the employment or acceptance dispatch order date for the relevant employee, it will be replaced by that order date.

```typescript
saveAmount(shoyoShikyukojoAmountDataList): Promise<void>;
```

--------------------------------

### readAll

Source: https://wiki.combosite-func.jp/api/classes/CombositeKimmuBashoDataService

Retrieves all work location data. This method is inherited from CombositeKimmuBashoDataProviderServiceBase.

```APIDOC
## readAll()

### Description
Retrieves all work location data.

### Method
(Implicitly invoked via SDK)

### Endpoint
(Not applicable, SDK method)

### Parameters
None

### Response
#### Success Response
- `Promise<KimmuBashoDataEntity[]>`: An array of work location data entities.

### Response Example
```json
[
  {
    "example_field": "example_value"
  }
]
```

### Example Usage
```js
const response = await combositeDataService.kimmuBashoData.readAll()
```
```

--------------------------------

### Paginate Custom Data

Source: https://wiki.combosite-func.jp/api/classes/UserCustomDataService

Recommended for retrieving large amounts of custom data. Use pagination with `orderBy`, `limit`, and `startAfter` to efficiently fetch data in chunks.

```typescript
const PAGE_SIZE = 100
let last = null
while (true) {
  const page = await service.getCustomDataByQuery((qb) =>
    last
      ? qb.orderBy('docId', 'desc').startAfter(last.docId).limit(PAGE_SIZE)
      : qb.orderBy('docId', 'desc').limit(PAGE_SIZE)
  )
  if (page.length < PAGE_SIZE) break
  last = page[page.length - 1]
}
```