### Install BIR1 Node.js Client

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Installs the 'bir1' package using npm. This is the first step to using the library in a Node.js project.

```bash
npm install bir1
```

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

### Full Integration Example with BIR1 (JavaScript)

Source: https://context7.com/pawel-id/bir1/llms.txt

A comprehensive example demonstrating production usage of the BIR1 library. It includes initializing the library with an API key and normalization function, performing searches, retrieving detailed reports, fetching PKD codes, and implementing robust error handling with automatic logout.

```javascript
import Bir, { BirError } from 'bir1'
import { modern } from 'bir1/normalize'

async function lookupCompany(identifier) {
  const bir = new Bir({
    key: process.env.GUS_API_KEY,
    normalizeFn: modern
  })

  try {
    // Search by NIP
    const basicInfo = await bir.search({ nip: identifier })
    console.log('Basic info:', basicInfo)

    // Get detailed report using REGON from search result
    const detailedReport = await bir.report({
      regon: basicInfo.regon,
      report: 'BIR11OsPrawna'
    })
    console.log('Detailed report:', detailedReport)

    // Get PKD codes
    const pkdCodes = await bir.report({
      regon: basicInfo.regon,
      report: 'BIR11OsPrawnaPkd'
    })
    console.log('PKD codes:', pkdCodes)

    return { basicInfo, detailedReport, pkdCodes }
  } catch (error) {
    if (error instanceof BirError) {
      console.error('GUS API error:', error.message)
    }
    throw error
  } finally {
    await bir.logout()
  }
}

// Usage
const companyData = await lookupCompany('5261040567')
```

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

### Quick Start: Search Entity with BIR1 Node.js Client

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Demonstrates how to quickly start using the 'bir1' library to search for an entity by its NIP (Tax Identification Number). It initializes the Bir client and calls the search method, logging the result to the console. The output shows a JSON object containing entity details.

```javascript
import Bir from 'bir1'

const bir = new Bir()
console.log(await bir.search({ nip: '5261040567' }))
// output:
// {
// Regon: '012100784',
// Nip: '5260250995',
// StatusNip: '',
// Nazwa: 'ORANGE POLSKA SPÓŁKA AKCYJNA',
// Wojewodztwo: 'MAZOWIECKIE',
// Powiat: 'm. st. Warszawa',
// Gmina: 'Ochota',
// Miejscowosc: 'Warszawa',
// KodPocztowy: '02-326',
//   ...
// }
```

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

### Retrieve Summary Reports with BIR1 Library

Source: https://context7.com/pawel-id/bir1/llms.txt

Shows how to use the `summary()` method to get bulk change reports (added, updated, removed) within a specified date range (up to one week prior). Requires the 'bir1' package. Input includes a date string and a report type. Output is a list of changed entities.

```javascript
import Bir from 'bir1'

const bir = new Bir()
const date = '2024-01-15' // Format: YYYY-MM-DD, not earlier than 1 week ago

// Get newly registered legal entities and physical person activities
const newEntities = await bir.summary({
  date,
  report: 'BIR11NowePodmiotyPrawneOrazDzialalnosciOsFizycznych'
})

// Get updated entities
const updatedEntities = await bir.summary({
  date,
  report: 'BIR11AktualizowanePodmiotyPrawneOrazDzialalnosciOsFizycznych'
})

// Get deleted/removed entities
const deletedEntities = await bir.summary({
  date,
  report: 'BIR11SkreslonePodmiotyPrawneOrazDzialalnosciOsFizycznych'
})

// Local units changes
const newLocalUnits = await bir.summary({ date, report: 'BIR11NoweJednostkiLokalne' })
const updatedLocalUnits = await bir.summary({ date, report: 'BIR11AktualizowaneJednostkiLokalne' })
const deletedLocalUnits = await bir.summary({ date, report: 'BIR11SkresloneJednostkiLokalne' })

```

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

### GET /value

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Retrieves specific diagnostic information or status values from the service.

```APIDOC
## GET /value

### Description
Retrieves diagnostic information based on the requested key.

### Method
GET

### Endpoint
/value

### Parameters
#### Query Parameters
- **value** (string) - Required - The diagnostic value to retrieve (e.g., StanDanych, StatusSesji, StatusUslugi).
```

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

### Get Diagnostic Values using BIR1 Library

Source: https://context7.com/pawel-id/bir1/llms.txt

Explains how to retrieve diagnostic information about the API session and service status using the `value()` method. Requires the 'bir1' package. Input is a diagnostic key string. Output is the corresponding diagnostic value.

```javascript
import Bir from 'bir1'

const bir = new Bir()

// Get database state date
const dataState = await bir.value('StanDanych')
console.log('Data state:', dataState) // e.g., "2024-01-15"

// Get service status (1 = available, 0 = unavailable)
const serviceStatus = await bir.value('StatusUslugi')
console.log('Service status:', serviceStatus)

// Get service message
const serviceMessage = await bir.value('KomunikatUslugi')
console.log('Service message:', serviceMessage)

// Get session status (1 = active, 0 = inactive)
const sessionStatus = await bir.value('StatusSesji')
console.log('Session status:', sessionStatus)

// Get last operation result code
const errorCode = await bir.value('KomunikatKod')
console.log('Last error code:', errorCode)

// Get last operation message
const errorMessage = await bir.value('KomunikatTresc')
console.log('Last message:', errorMessage)

```

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

### Login to BIR1 API

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Authenticates with the BIR1 API using a provided key. The session ID is stored for subsequent requests. Starting from version 3.0, this method is optional as it's called automatically.

```javascript
import Bir from 'bir1';

const bir = new Bir();
await bir.login();
```

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

### Get Diagnostic Information from BIR1 API

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Retrieves specific diagnostic information from the BIR1 API. The 'value' parameter determines the type of information requested, such as data status, message codes, or session status.

```javascript
import Bir from 'bir1';

const bir = new Bir();
const dataStatus = await bir.value('StanDanych');
console.log(dataStatus);
```

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

### Handle API Errors with BirError (JavaScript)

Source: https://context7.com/pawel-id/bir1/llms.txt

Illustrates how to use the custom BirError class to catch and handle API-specific errors returned by the BIR1 library. It shows how to access detailed response information, including error codes and messages, and provides examples of common error codes.

```javascript
import Bir, { BirError } from 'bir1'

const bir = new Bir()

try {
  const result = await bir.search({ nip: 'invalid-nip' })
} catch (error) {
  if (error instanceof BirError) {
    console.error('BIR API Error:', error.message)
    console.error('Response details:', error.response)
    // error.response may contain:
    // { ErrorCode: '4', ErrorMessagePl: 'Nie znaleziono podmiotów.' }
  } else {
    console.error('Unexpected error:', error)
  }
}

// Check error codes after operations
const errorCode = await bir.value('KomunikatKod')
// '0' = success
// '4' = entity not found
// '5' = invalid report name
// '7' = session expired
```

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

### Initialize BIR1 Client Instance

Source: https://context7.com/pawel-id/bir1/llms.txt

Demonstrates how to instantiate the Bir class for either test or production environments. It also shows how to apply optional response normalization functions for cleaner data output.

```javascript
import Bir from 'bir1'
import { modern } from 'bir1/normalize'

// Using the test environment
const birTest = new Bir()

// Using production environment with API key
const birProd = new Bir({ key: 'your-production-api-key' })

// With custom response normalization
const birNormalized = new Bir({
  key: process.env.GUS_API_KEY,
  normalizeFn: modern
})
```

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

### Manage Sessions with BIR1 Library (JavaScript)

Source: https://context7.com/pawel-id/bir1/llms.txt

Demonstrates how to initialize the BIR1 library, perform manual login, execute searches using the managed session, and explicitly log out. Session management is handled automatically on the first API call if not done manually.

```javascript
import Bir from 'bir1'

const bir = new Bir({ key: process.env.GUS_API_KEY })

// Manual login (optional - called automatically when needed)
await bir.login()

// Perform searches (session is reused)
const result1 = await bir.search({ nip: '5261040567' })
const result2 = await bir.search({ regon: '012100784' })

// Explicit logout when done (optional)
await bir.logout()
```

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

### POST /summary

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Retrieves a summary report of database changes for a specific date.

```APIDOC
## POST /summary

### Description
Retrieves a summary of changes in the database for a given date.

### Method
POST

### Endpoint
/summary

### Parameters
#### Request Body
- **date** (string) - Required - Date in YYYY-MM-DD format.
- **report** (string) - Required - The type of summary report.
```

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

### POST /search

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Searches for entity information using NIP, REGON, or KRS identifiers.

```APIDOC
## POST /search

### Description
Returns basic information about an entity based on provided identifiers.

### Method
POST

### Endpoint
/search

### Parameters
#### Request Body
- **nip** (string) - Optional - NIP number
- **regon** (string) - Optional - REGON number
- **krs** (string) - Optional - KRS number

### Request Example
{
  "nip": "5261040567"
}
```

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

### Fetch Various Report Types using BIR1 Library

Source: https://context7.com/pawel-id/bir1/llms.txt

Demonstrates how to fetch different types of reports for legal entities, physical persons, and local units using the BIR1 library. Requires the 'bir1' package. Input is a REGON identifier and a report type string. Output varies based on the report type.

```javascript
import Bir from 'bir1'

const bir = new Bir()
const regon = '010058960'

// Legal entities (Osoby Prawne)
await bir.report({ regon, report: 'BIR11OsPrawna' })           // General data
await bir.report({ regon, report: 'BIR11OsPrawnaPkd' })        // PKD codes
await bir.report({ regon, report: 'BIR11OsPrawnaListaJednLokalnych' }) // Local units
await bir.report({ regon, report: 'BIR11OsPrawnaSpCywilnaWspolnicy' }) // Partners (civil partnerships)

// Physical persons (Osoby Fizyczne) - use appropriate REGON
await bir.report({ regon: 'fizRegon', report: 'BIR11OsFizycznaDaneOgolne' })
await bir.report({ regon: 'fizRegon', report: 'BIR11OsFizycznaDzialalnoscCeidg' })
await bir.report({ regon: 'fizRegon', report: 'BIR11OsFizycznaPkd' })

// Local units
await bir.report({ regon, report: 'BIR11JednLokalnaOsPrawnej' })
await bir.report({ regon, report: 'BIR11JednLokalnaOsPrawnejPkd' })

// Entity type determination
await bir.report({ regon, report: 'BIR11TypPodmiotu' })
```

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

### Default Data Fetching - bir1

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Demonstrates the default behavior of the bir1 library when fetching reports. The data is returned in its original SOAP message format, often with prefixes like 'praw_' and inconsistent casing.

```javascript
import Bir from 'bir1'
const bir = new Bir()
console.log(
  await bir.report({
    regon: '010058960',
    report: 'BIR11OsPrawna',
  })
)
// output:
// {
//   praw_regon9: '010058960',
//   praw_nip: '5220002334',
//   praw_statusNip: '',
//   praw_nazwa: 'POLSKIE LINIE LOTNICZE "LOT" SPÓŁKA AKCYJNA',
//   praw_nazwaSkrocona: '',
//   ...
// }
```

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

### POST /login

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Authenticates the client with the GUS API. The session ID is stored automatically for subsequent requests.

```APIDOC
## POST /login

### Description
Logs the user into the API using the provided key. Session management is handled automatically.

### Method
POST

### Endpoint
/login

### Response
#### Success Response (200)
- **status** (string) - Indicates successful authentication.
```

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

### Search Business Entities by Identifier

Source: https://context7.com/pawel-id/bir1/llms.txt

Shows how to use the search method to retrieve entity information using NIP, REGON, or KRS numbers. The method returns a structured object containing registration and address details.

```javascript
import Bir from 'bir1'

const bir = new Bir()

// Search by NIP
const byNip = await bir.search({ nip: '5261040567' })

// Search by REGON
const byRegon = await bir.search({ regon: '012100784' })

// Search by KRS
const byKrs = await bir.search({ krs: '0000010681' })
```

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

### Normalize BIR1 API Responses with Normalization Functions

Source: https://context7.com/pawel-id/bir1/llms.txt

Illustrates how to use optional normalization functions (`legacy`, `modern`) from the 'bir1/normalize' module to transform raw API responses into cleaner formats. Requires the 'bir1' package and normalization functions. Input is a report query object. Output is a normalized response object.

```javascript
import Bir from 'bir1'
import { legacy, modern } from 'bir1/normalize'

const reportQuery = { regon: '010058960', report: 'BIR11OsPrawna' }

// Default: raw response (keys as returned by API)
const birRaw = new Bir()
const rawResult = await birRaw.report(reportQuery)
console.log(rawResult)
// { praw_regon9: '010058960', praw_nip: '5220002334', ... }

// Legacy normalization (v2.x compatibility)
// - Removes 'praw_' prefix
// - Lowercases first letter
// - Replaces empty strings with undefined
const birLegacy = new Bir({ normalizeFn: legacy })
const legacyResult = await birLegacy.report(reportQuery)
console.log(legacyResult)
// { regon9: '010058960', nip: '5220002334', statusNip: undefined, ... }

// Modern normalization (recommended)
// - Removes all prefixes (fiz_, praw_, lokfiz_, lokpraw_, etc.)
// - Converts keys to lowerCamelCase
// - Unifies key names (regon9 -> regon)
// - Replaces empty strings with undefined
const birModern = new Bir({ normalizeFn: modern })
const modernResult = await birModern.report(reportQuery)
console.log(modernResult)
// { regon: '010058960', nip: '5220002334', statusNip: undefined, ... }

```

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

### Custom Normalization Function - bir1

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Illustrates how to provide a custom normalization function to the bir1 library. This allows developers to define their own logic for processing the response data according to specific requirements.

```javascript
import Bir from 'bir1'

// Define your custom normalization function
const customNormalize = (data) => {
  // Your custom logic here
  return data;
};

const bir = new Bir({ normalizeFn: customNormalize })
console.log(
  await bir.report({
    regon: '010058960',
    report: 'BIR11OsPrawna',
  })
)
```

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

### POST /report

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Retrieves a detailed report for a specific entity identified by its REGON number.

```APIDOC
## POST /report

### Description
Fetches a full report for an entity based on the specified report type.

### Method
POST

### Endpoint
/report

### Parameters
#### Request Body
- **regon** (string) - Required - REGON number
- **report** (string) - Required - The type of report to generate (e.g., PublDaneRaportPrawna).
```

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

### Retrieve Summary Reports from BIR1 API

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Retrieves a summary of changes from the BIR1 API database. Requires a query object with a date (YYYY-MM-DD) and a specific report type indicating the nature of the summary (e.g., new entities, updated entities).

```javascript
import Bir from 'bir1';

const bir = new Bir();
console.log(await bir.summary({ date: '2023-10-27', report: 'BIR11NowePodmiotyPrawneOrazDzialalnosciOsFizycznych' }));
```

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

### Search for Entities in BIR1 API

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Searches for entities in the BIR1 API using NIP, REGON, or KRS numbers. Returns basic information about the found entity. Requires a query object with one of the identification numbers.

```javascript
import Bir from 'bir1';

const bir = new Bir();
console.log(await bir.search({ nip: '5261040567' }));
```

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

### Retrieve Detailed Reports from BIR1 API

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Fetches detailed reports about an entity from the BIR1 API. The 'query' object must include the REGON number and the desired report type from a predefined list.

```javascript
import Bir from 'bir1';

const bir = new Bir();
console.log(await bir.report({ regon: '012100784', report: 'PublDaneRaportPrawna' }));
```

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

### Normalized Data Fetching (Modern) - bir1

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Shows how to use the 'modern' normalization function provided by bir1 to clean up the response data. This function removes prefixes, converts keys to camel case, and unifies certain keys for a more consistent output.

```javascript
import Bir from 'bir1'
import { modern } from 'bir1/normalize'
const bir = new Bir({ normalizeFn: modern })
console.log(
  await bir.report({
    regon: '010058960',
    report: 'BIR11OsPrawna',
  })
)
// output:
// {
//   regon: '010058960',
//   nip: '5220002334',
//   statusNip: undefined,
//   nazwa: 'POLSKIE LINIE LOTNICZE "LOT" SPÓŁKA AKCYJNA',
//   nazwaSkrocona: undefined,
//   ...
// }
```

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

### Retrieve Detailed Entity Reports

Source: https://context7.com/pawel-id/bir1/llms.txt

Demonstrates the report method to fetch comprehensive data for an entity. Users must provide the REGON number and specify the report type, such as legal entity details or PKD activity codes.

```javascript
import Bir from 'bir1'

const bir = new Bir()

// Get detailed report for a legal entity
const legalEntityReport = await bir.report({
  regon: '011417295',
  report: 'BIR11OsPrawna'
})

// Get PKD business activity codes
const pkdReport = await bir.report({
  regon: '011417295',
  report: 'BIR11OsPrawnaPkd'
})
```

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

### Logout from BIR1 API

Source: https://github.com/pawel-id/bir1/blob/master/README.md

Logs out the current session from the BIR1 API, invalidating the session ID.

```javascript
import Bir from 'bir1';

const bir = new Bir();
await bir.logout();
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.