@jars-lt/sdk 1.0.0

package/README.md

@@ -0,0 +1,287 @@
+# @jars-lt/sdk
+
+Official Node.js SDK for [JARS.LT](https://jars.lt) - Lithuanian Company Registry API
+
+## Installation
+
+```bash
+npm install @jars-lt/sdk
+# or
+yarn add @jars-lt/sdk
+# or
+pnpm add @jars-lt/sdk
+```
+
+## Quick Start
+
+```typescript
+import { JarsClient } from '@jars-lt/sdk';
+
+// Initialize the client
+const client = new JarsClient({
+  apiKey: 'your_api_key_here'
+});
+
+// Search for companies
+const companies = await client.searchCompanies({
+  q: 'UAB Maxima',
+  limit: 10
+});
+
+console.log(companies.results);
+```
+
+## API Key
+
+Get your API key at [jars.lt](https://jars.lt). Available plans:
+- **Free**: 300 requests/month
+- **Starter**: 5,000 requests/month
+- **Professional**: 50,000 requests/month
+- **Enterprise**: 1,000,000 requests/month
+
+## Usage
+
+### Initialize Client
+
+```typescript
+import { JarsClient } from '@jars-lt/sdk';
+
+const client = new JarsClient({
+  apiKey: 'your_api_key_here',
+  // Optional: custom base URL
+  baseURL: 'https://api.jars.lt/api/v1',
+  // Optional: request timeout in ms
+  timeout: 30000
+});
+```
+
+### Search Companies
+
+Search for Lithuanian companies by name or code:
+
+```typescript
+const results = await client.searchCompanies({
+  q: 'Maxima',
+  limit: 10,
+  offset: 0
+});
+
+console.log(`Found ${results.total} companies`);
+results.results.forEach(company => {
+  console.log(`${company.name} (${company.code})`);
+});
+```
+
+### Get Company by Code
+
+Retrieve detailed information about a specific company:
+
+```typescript
+const company = await client.getCompany('111111111');
+
+console.log(company.name);
+console.log(company.address);
+console.log(company.status);
+console.log(company.registrationDate);
+```
+
+### Search Addresses
+
+Search for streets, settlements, and municipalities. Supports multi-word search:
+
+```typescript
+const results = await client.searchAddresses({
+  q: 'kaunas basanavi',
+  limit: 5
+});
+
+// Streets
+results.streets.forEach(street => {
+  console.log(`${street.name} ${street.typeAbbr}`);
+  if (street.settlement) {
+    console.log(`  ${street.settlement.name}`);
+  }
+});
+
+// Settlements
+results.settlements.forEach(settlement => {
+  console.log(`${settlement.name} ${settlement.typeAbbr}`);
+});
+
+// Municipalities
+results.municipalities.forEach(municipality => {
+  console.log(municipality.name);
+});
+```
+
+### Get Location by Postal Code
+
+Get county, municipality, settlement, and streets for a postal code:
+
+```typescript
+const location = await client.getByPostalCode('54306');
+// or with LT- prefix
+const location = await client.getByPostalCode('LT-54306');
+
+console.log('County:', location.county.name);
+console.log('Municipality:', location.municipality.name);
+console.log('Settlement:', location.settlement.name);
+
+// All streets with this postal code
+location.streets?.forEach(street => {
+  console.log(`${street.name} ${street.typeAbbr}`);
+});
+```
+
+### Get Usage Statistics
+
+Check your current API usage and limits:
+
+```typescript
+const usage = await client.getUsage();
+
+console.log('Plan:', usage.plan);
+console.log('Requests used:', usage.requestCount);
+console.log('Requests remaining:', usage.remaining);
+console.log('Monthly limit:', usage.limit);
+console.log('Resets on:', usage.resetDate);
+console.log('Rate limit:', usage.rateLimit, 'requests/minute');
+```
+
+## Error Handling
+
+The SDK throws `JarsAPIError` for API errors:
+
+```typescript
+import { JarsClient, JarsAPIError } from '@jars-lt/sdk';
+
+try {
+  const company = await client.getCompany('invalid');
+} catch (error) {
+  if (error instanceof JarsAPIError) {
+    console.error('API Error:', error.message);
+    console.error('Status Code:', error.statusCode);
+    console.error('Response:', error.response);
+  } else {
+    console.error('Network Error:', error);
+  }
+}
+```
+
+Common error codes:
+- `400` - Invalid parameters
+- `401` - Invalid API key
+- `404` - Resource not found
+- `429` - Rate limit exceeded
+- `500` - Server error
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes full type definitions:
+
+```typescript
+import { JarsClient, Company, SubscriptionPlan } from '@jars-lt/sdk';
+
+const client = new JarsClient({ apiKey: 'key' });
+
+// Fully typed responses
+const company: Company = await client.getCompany('111111111');
+const usage = await client.getUsage();
+const plan: SubscriptionPlan = usage.plan; // 'FREE' | 'STARTER' | 'PROFESSIONAL' | 'ENTERPRISE'
+```
+
+## Advanced Usage
+
+### Custom Axios Configuration
+
+The SDK uses axios internally. You can access the underlying axios instance if needed:
+
+```typescript
+import { JarsClient } from '@jars-lt/sdk';
+
+const client = new JarsClient({
+  apiKey: 'key',
+  timeout: 60000, // 60 seconds
+  baseURL: 'https://custom-api.example.com/api/v1'
+});
+```
+
+### Pagination
+
+Handle large result sets with pagination:
+
+```typescript
+async function getAllCompanies(query: string) {
+  const pageSize = 100; // Max allowed
+  let offset = 0;
+  let allCompanies = [];
+
+  while (true) {
+    const results = await client.searchCompanies({
+      q: query,
+      limit: pageSize,
+      offset
+    });
+
+    allCompanies.push(...results.results);
+
+    if (results.results.length < pageSize) {
+      break; // Last page
+    }
+
+    offset += pageSize;
+  }
+
+  return allCompanies;
+}
+```
+
+## Examples
+
+### Find Company and Its Address
+
+```typescript
+const companies = await client.searchCompanies({ q: 'Maxima' });
+if (companies.results.length > 0) {
+  const company = await client.getCompany(companies.results[0].code);
+  console.log(`${company.name} is located at ${company.address}`);
+}
+```
+
+### Search Streets in Kaunas
+
+```typescript
+const results = await client.searchAddresses({ q: 'kaunas' });
+console.log(`Found ${results.streets.length} streets in Kaunas`);
+```
+
+### Check if API Key is Valid
+
+```typescript
+try {
+  const usage = await client.getUsage();
+  console.log('API key is valid. Plan:', usage.plan);
+} catch (error) {
+  console.error('Invalid API key');
+}
+```
+
+## Rate Limits
+
+Respect rate limits based on your plan:
+- **Free**: 30 requests/minute
+- **Starter**: 60 requests/minute
+- **Professional**: 300 requests/minute
+- **Enterprise**: 1000 requests/minute
+
+The API returns `429 Too Many Requests` when rate limit is exceeded.
+
+## Support
+
+- Documentation: [jars.lt/docs](https://jars.lt/docs)
+- Issues: [GitHub Issues](https://github.com/your-org/jars-lt-sdk/issues)
+- Contact: [jars.lt/contact](https://jars.lt/contact)
+
+## License
+
+MIT © UAB Sistemium

package/dist/index.d.ts

@@ -0,0 +1,219 @@
+import { Company, SubscriptionPlan } from '@jars-lt/types';
+/**
+ * Configuration options for JARS.LT client
+ */
+export interface JarsClientConfig {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for API (default: https://api.jars.lt/api/v1) */
+    baseURL?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Search results response
+ */
+export interface SearchCompaniesResponse {
+    results: Company[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Address search results
+ */
+export interface SearchAddressesResponse {
+    streets: Array<{
+        code: number;
+        name: string;
+        typeAbbr: string;
+        settlementId: string;
+        buildings?: Array<{
+            number: string;
+            postalCode?: string;
+        }>;
+        settlement?: {
+            name: string;
+            typeAbbr: string;
+        };
+    }>;
+    settlements: Array<{
+        code: number;
+        name: string;
+        typeAbbr: string;
+        municipalityId: string;
+    }>;
+    municipalities: Array<{
+        code: number;
+        name: string;
+    }>;
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Postal code lookup response
+ */
+export interface PostalCodeResponse {
+    postalCode: string;
+    streets?: Array<{
+        code: number;
+        name: string;
+        type: string;
+        typeAbbr: string;
+    }>;
+    settlement: {
+        code: number;
+        name: string;
+        type: string;
+        typeAbbr: string;
+    };
+    eldership?: {
+        code: number;
+        name: string;
+    };
+    municipality: {
+        code: number;
+        name: string;
+    };
+    county: {
+        code: number;
+        name: string;
+    };
+}
+/**
+ * Usage statistics response
+ */
+export interface UsageResponse {
+    plan: SubscriptionPlan;
+    requestCount: number;
+    limit: number;
+    remaining: number;
+    resetDate: string;
+    dataDelay: number;
+    rateLimit: number;
+    webhooksEnabled: boolean;
+}
+/**
+ * API Error
+ */
+export declare class JarsAPIError extends Error {
+    statusCode?: number | undefined;
+    response?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
+}
+/**
+ * Official JARS.LT API Client
+ *
+ * @example
+ * ```typescript
+ * import { JarsClient } from '@jars-lt/sdk';
+ *
+ * const client = new JarsClient({
+ *   apiKey: 'your_api_key_here'
+ * });
+ *
+ * // Search companies
+ * const companies = await client.searchCompanies({ q: 'UAB Maxima' });
+ *
+ * // Get company by code
+ * const company = await client.getCompany('111111111');
+ * ```
+ */
+export declare class JarsClient {
+    private client;
+    constructor(config: JarsClientConfig);
+    /**
+     * Search for companies by name, code, or other criteria
+     *
+     * @param params - Search parameters
+     * @param params.q - Search query (company name or code)
+     * @param params.limit - Number of results (max: 100, default: 20)
+     * @param params.offset - Skip results (default: 0)
+     * @returns Search results with companies
+     *
+     * @example
+     * ```typescript
+     * const results = await client.searchCompanies({
+     *   q: 'Maxima',
+     *   limit: 10
+     * });
+     * console.log(results.total); // Total matching companies
+     * console.log(results.results); // Array of companies
+     * ```
+     */
+    searchCompanies(params: {
+        q: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<SearchCompaniesResponse>;
+    /**
+     * Get company details by company code
+     *
+     * @param code - Company code (9 digits)
+     * @returns Company details
+     *
+     * @example
+     * ```typescript
+     * const company = await client.getCompany('111111111');
+     * console.log(company.name); // Company name
+     * console.log(company.address); // Company address
+     * ```
+     */
+    getCompany(code: string): Promise<Company>;
+    /**
+     * Search for addresses (streets, settlements, municipalities)
+     * Supports multi-word search (e.g., "kaunas basanavi")
+     *
+     * @param params - Search parameters
+     * @param params.q - Search query (street, settlement, or municipality name)
+     * @param params.limit - Number of results (max: 100, default: 20)
+     * @param params.offset - Skip results (default: 0)
+     * @returns Search results grouped by type
+     *
+     * @example
+     * ```typescript
+     * const results = await client.searchAddresses({
+     *   q: 'kaunas basanavi',
+     *   limit: 5
+     * });
+     * console.log(results.streets); // Matching streets
+     * console.log(results.settlements); // Matching settlements
+     * ```
+     */
+    searchAddresses(params: {
+        q: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<SearchAddressesResponse>;
+    /**
+     * Get location information by postal code
+     *
+     * @param code - Postal code (5 digits, with or without "LT-" prefix)
+     * @returns Location details including county, municipality, settlement, and streets
+     *
+     * @example
+     * ```typescript
+     * const location = await client.getByPostalCode('54306');
+     * console.log(location.county.name); // County name
+     * console.log(location.streets); // Streets with this postal code
+     * ```
+     */
+    getByPostalCode(code: string): Promise<PostalCodeResponse>;
+    /**
+     * Get current API usage statistics and limits
+     *
+     * @returns Usage information including request count and limits
+     *
+     * @example
+     * ```typescript
+     * const usage = await client.getUsage();
+     * console.log(usage.plan); // Current subscription plan
+     * console.log(usage.remaining); // Remaining requests this month
+     * console.log(usage.resetDate); // When the counter resets
+     * ```
+     */
+    getUsage(): Promise<UsageResponse>;
+}
+export * from '@jars-lt/types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC3D,UAAU,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC;KACjD,CAAC,CAAC;IACH,WAAW,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC,CAAC;IACH,cAAc,EAAE,KAAK,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,UAAU,EAAE;QACV,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,SAAS,CAAC,EAAE;QACV,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,YAAY,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,gBAAgB,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAG5B,UAAU,CAAC,EAAE,MAAM;IACnB,QAAQ,CAAC,EAAE,GAAG;gBAFrB,OAAO,EAAE,MAAM,EACR,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,QAAQ,CAAC,EAAE,GAAG,YAAA;CAKxB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,EAAE,gBAAgB;IA+BpC;;;;;;;;;;;;;;;;;;OAkBG;IACG,eAAe,CAAC,MAAM,EAAE;QAC5B,CAAC,EAAE,MAAM,CAAC;QACV,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAKpC;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKhD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,eAAe,CAAC,MAAM,EAAE;QAC5B,CAAC,EAAE,MAAM,CAAC;QACV,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAKpC;;;;;;;;;;;;OAYG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAKhE;;;;;;;;;;;;OAYG;IACG,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC;CAIzC;AAGD,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,176 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JarsClient = exports.JarsAPIError = void 0;
+const axios_1 = __importDefault(require("axios"));
+/**
+ * API Error
+ */
+class JarsAPIError extends Error {
+    constructor(message, statusCode, response) {
+        super(message);
+        this.statusCode = statusCode;
+        this.response = response;
+        this.name = 'JarsAPIError';
+    }
+}
+exports.JarsAPIError = JarsAPIError;
+/**
+ * Official JARS.LT API Client
+ *
+ * @example
+ * ```typescript
+ * import { JarsClient } from '@jars-lt/sdk';
+ *
+ * const client = new JarsClient({
+ *   apiKey: 'your_api_key_here'
+ * });
+ *
+ * // Search companies
+ * const companies = await client.searchCompanies({ q: 'UAB Maxima' });
+ *
+ * // Get company by code
+ * const company = await client.getCompany('111111111');
+ * ```
+ */
+class JarsClient {
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error('API key is required');
+        }
+        this.client = axios_1.default.create({
+            baseURL: config.baseURL || 'https://api.jars.lt/api/v1',
+            timeout: config.timeout || 30000,
+            headers: {
+                'x-api-key': config.apiKey,
+                'Content-Type': 'application/json',
+            },
+        });
+        // Add error interceptor
+        this.client.interceptors.response.use((response) => response, (error) => {
+            if (error.response) {
+                const message = error.response.data?.error || error.response.data?.message || error.message;
+                throw new JarsAPIError(message, error.response.status, error.response.data);
+            }
+            throw new JarsAPIError(error.message);
+        });
+    }
+    /**
+     * Search for companies by name, code, or other criteria
+     *
+     * @param params - Search parameters
+     * @param params.q - Search query (company name or code)
+     * @param params.limit - Number of results (max: 100, default: 20)
+     * @param params.offset - Skip results (default: 0)
+     * @returns Search results with companies
+     *
+     * @example
+     * ```typescript
+     * const results = await client.searchCompanies({
+     *   q: 'Maxima',
+     *   limit: 10
+     * });
+     * console.log(results.total); // Total matching companies
+     * console.log(results.results); // Array of companies
+     * ```
+     */
+    async searchCompanies(params) {
+        const response = await this.client.get('/companies/search', { params });
+        return response.data;
+    }
+    /**
+     * Get company details by company code
+     *
+     * @param code - Company code (9 digits)
+     * @returns Company details
+     *
+     * @example
+     * ```typescript
+     * const company = await client.getCompany('111111111');
+     * console.log(company.name); // Company name
+     * console.log(company.address); // Company address
+     * ```
+     */
+    async getCompany(code) {
+        const response = await this.client.get(`/companies/${code}`);
+        return response.data;
+    }
+    /**
+     * Search for addresses (streets, settlements, municipalities)
+     * Supports multi-word search (e.g., "kaunas basanavi")
+     *
+     * @param params - Search parameters
+     * @param params.q - Search query (street, settlement, or municipality name)
+     * @param params.limit - Number of results (max: 100, default: 20)
+     * @param params.offset - Skip results (default: 0)
+     * @returns Search results grouped by type
+     *
+     * @example
+     * ```typescript
+     * const results = await client.searchAddresses({
+     *   q: 'kaunas basanavi',
+     *   limit: 5
+     * });
+     * console.log(results.streets); // Matching streets
+     * console.log(results.settlements); // Matching settlements
+     * ```
+     */
+    async searchAddresses(params) {
+        const response = await this.client.get('/addresses/search', { params });
+        return response.data;
+    }
+    /**
+     * Get location information by postal code
+     *
+     * @param code - Postal code (5 digits, with or without "LT-" prefix)
+     * @returns Location details including county, municipality, settlement, and streets
+     *
+     * @example
+     * ```typescript
+     * const location = await client.getByPostalCode('54306');
+     * console.log(location.county.name); // County name
+     * console.log(location.streets); // Streets with this postal code
+     * ```
+     */
+    async getByPostalCode(code) {
+        const response = await this.client.get(`/addresses/postal/${code}`);
+        return response.data;
+    }
+    /**
+     * Get current API usage statistics and limits
+     *
+     * @returns Usage information including request count and limits
+     *
+     * @example
+     * ```typescript
+     * const usage = await client.getUsage();
+     * console.log(usage.plan); // Current subscription plan
+     * console.log(usage.remaining); // Remaining requests this month
+     * console.log(usage.resetDate); // When the counter resets
+     * ```
+     */
+    async getUsage() {
+        const response = await this.client.get('/usage');
+        return response.data;
+    }
+}
+exports.JarsClient = JarsClient;
+// Re-export types from @jars-lt/types for convenience
+__exportStar(require("@jars-lt/types"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/example.ts

@@ -0,0 +1,97 @@
+/**
+ * Example usage of @jars-lt/sdk
+ *
+ * To run this example:
+ * 1. Set your API key: export JARS_API_KEY=your_api_key_here
+ * 2. Run: tsx example.ts
+ */
+
+import { JarsClient, JarsAPIError } from './src/index';
+
+async function main() {
+  // Initialize client with API key from environment
+  const apiKey = process.env.JARS_API_KEY || 'your_api_key_here';
+  const client = new JarsClient({ apiKey });
+
+  console.log('🔑 JARS.LT SDK Example\n');
+
+  try {
+    // Example 1: Get usage statistics
+    console.log('📊 Getting usage statistics...');
+    const usage = await client.getUsage();
+    console.log(`Plan: ${usage.plan}`);
+    console.log(`Requests used: ${usage.requestCount}/${usage.limit}`);
+    console.log(`Remaining: ${usage.remaining}`);
+    console.log(`Rate limit: ${usage.rateLimit} requests/minute\n`);
+
+    // Example 2: Search companies
+    console.log('🏢 Searching companies...');
+    const companies = await client.searchCompanies({
+      q: 'Maxima',
+      limit: 3,
+    });
+    console.log(`Found ${companies.total} companies total`);
+    companies.results.forEach((company) => {
+      console.log(`  - ${company.name} (${company.code})`);
+    });
+    console.log();
+
+    // Example 3: Get specific company
+    if (companies.results.length > 0) {
+      const companyCode = companies.results[0].code;
+      console.log(`📄 Getting details for company ${companyCode}...`);
+      const company = await client.getCompany(companyCode);
+      console.log(`  Name: ${company.name}`);
+      console.log(`  Address: ${company.address}`);
+      console.log(`  Status: ${company.status}`);
+      console.log();
+    }
+
+    // Example 4: Search addresses
+    console.log('🗺️  Searching addresses...');
+    const addresses = await client.searchAddresses({
+      q: 'kaunas basanavi',
+      limit: 3,
+    });
+    console.log(`Found ${addresses.streets.length} streets`);
+    addresses.streets.forEach((street) => {
+      console.log(`  - ${street.name} ${street.typeAbbr}`);
+      if (street.settlement) {
+        console.log(`    ${street.settlement.name}`);
+      }
+    });
+    console.log();
+
+    // Example 5: Get location by postal code
+    console.log('📮 Getting location by postal code...');
+    const location = await client.getByPostalCode('54306');
+    console.log(`Postal Code: ${location.postalCode}`);
+    console.log(`County: ${location.county.name}`);
+    console.log(`Municipality: ${location.municipality.name}`);
+    console.log(`Settlement: ${location.settlement.name}`);
+    if (location.streets && location.streets.length > 0) {
+      console.log(`Streets (${location.streets.length} total):`);
+      location.streets.slice(0, 3).forEach((street) => {
+        console.log(`  - ${street.name} ${street.typeAbbr}`);
+      });
+      if (location.streets.length > 3) {
+        console.log(`  ... and ${location.streets.length - 3} more`);
+      }
+    }
+  } catch (error) {
+    if (error instanceof JarsAPIError) {
+      console.error('❌ API Error:', error.message);
+      console.error('Status Code:', error.statusCode);
+      if (error.statusCode === 401) {
+        console.error('💡 Make sure your API key is valid');
+      }
+    } else {
+      console.error('❌ Error:', error);
+    }
+    process.exit(1);
+  }
+
+  console.log('\n✅ Example completed successfully!');
+}
+
+main();

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@jars-lt/sdk",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for JARS.LT API - Lithuanian Company Registry",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "jars",
+    "lithuania",
+    "company-registry",
+    "api",
+    "sdk",
+    "client"
+  ],
+  "author": "UAB Sistemium",
+  "license": "MIT",
+  "homepage": "https://jars.lt",
+  "dependencies": {
+    "@jars-lt/types": "^1.0.0",
+    "axios": "^1.6.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.3"
+  }
+}