lt-open-data-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Giedrius Macevičius
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,366 @@
+# lt-open-data-sdk
+
+TypeScript SDK for the **Lithuanian Open Data platform** ([data.gov.lt](https://data.gov.lt)) powered by the Spinta engine.
+
+## Features
+
+- 🔍 **QueryBuilder** - Fluent API for constructing DSQL queries
+- 🌐 **SpintaClient** - HTTP client with automatic pagination
+- 🛠️ **CLI Type Generator** - Generate TypeScript interfaces from live API
+- 🔐 **OAuth Support** - Client credentials authentication _(untested)_
+
+## Installation
+
+```bash
+npm install lt-open-data-sdk
+```
+
+Requires Node.js ≥18 (uses native `fetch`).
+
+## Quick Start
+
+```typescript
+import { SpintaClient, QueryBuilder } from "lt-open-data-sdk";
+
+const client = new SpintaClient();
+
+// Fetch data with a query
+const query = new QueryBuilder()
+  .select("_id", "pavadinimas")
+  .filter((f) => f.field("sav_kodas").gt(10))
+  .sort("pavadinimas")
+  .limit(10);
+
+const data = await client.getAll(
+  "datasets/gov/rc/ar/savivaldybe/Savivaldybe",
+  query
+);
+console.log(data);
+```
+
+---
+
+## QueryBuilder
+
+Build type-safe queries with a fluent API:
+
+```typescript
+const query = new QueryBuilder<MyType>()
+  .select("field1", "field2") // Select specific fields
+  .filter((f) => f.field("x").eq(1)) // Add filters
+  .sort("field1") // Sort ascending
+  .sortDesc("field2") // Sort descending
+  .limit(100); // Limit results
+
+const queryString = query.toQueryString();
+// Returns: ?select(field1,field2)&x=1&sort(field1,-field2)&limit(100)
+```
+
+### Filter Operators
+
+| Method             | Query                     | Description           |
+| ------------------ | ------------------------- | --------------------- |
+| `.eq(value)`       | `field=value`             | Equals                |
+| `.ne(value)`       | `field!=value`            | Not equals            |
+| `.lt(value)`       | `field<value`             | Less than             |
+| `.le(value)`       | `field<=value`            | Less than or equal    |
+| `.gt(value)`       | `field>value`             | Greater than          |
+| `.ge(value)`       | `field>=value`            | Greater than or equal |
+| `.contains(str)`   | `field.contains("str")`   | Contains substring    |
+| `.startswith(str)` | `field.startswith("str")` | Starts with           |
+
+### Combining Filters
+
+```typescript
+// AND
+.filter(f => f.field('a').eq(1).and(f.field('b').eq(2)))
+// Output: a=1&b=2
+
+// OR
+.filter(f => f.field('a').eq(1).or(f.field('b').eq(2)))
+// Output: a=1|b=2
+
+// Complex (OR inside AND - auto-wrapped in parentheses)
+.filter(f => f.field('a').gt(10).and(
+  f.field('b').eq(1).or(f.field('b').eq(2))
+))
+// Output: a>10&(b=1|b=2)
+```
+
+---
+
+## SpintaClient
+
+### Basic Usage
+
+```typescript
+const client = new SpintaClient();
+// Uses https://get.data.gov.lt by default
+```
+
+### Methods
+
+#### `getAll(model, query?)` - Fetch one page
+
+```typescript
+const cities = await client.getAll("datasets/gov/example/City", query);
+// Returns: Array of objects (unwrapped from _data)
+```
+
+> ⚠️ **Note**: Returns ONE page only. Use `stream()` for all records.
+
+#### `getAllRaw(model, query?)` - Fetch with metadata
+
+```typescript
+const response = await client.getAllRaw("datasets/gov/example/City", query);
+// Returns: { _type, _data: [...], _page: { next } }
+```
+
+#### `getOne(model, id)` - Fetch by UUID
+
+```typescript
+const city = await client.getOne("datasets/gov/example/City", "uuid-here");
+```
+
+#### `count(model, query?)` - Count records
+
+```typescript
+const total = await client.count("datasets/gov/example/City");
+const filtered = await client.count(
+  "datasets/gov/example/City",
+  new QueryBuilder().filter((f) => f.field("population").gt(100000))
+);
+```
+
+#### `stream(model, query?)` - Paginated iteration
+
+```typescript
+for await (const city of client.stream("datasets/gov/example/City")) {
+  console.log(city.pavadinimas);
+}
+```
+
+#### `listNamespace(namespace)` - List namespace contents
+
+```typescript
+const items = await client.listNamespace("datasets/gov/rc");
+// Returns: [{ _id: 'path', _type: 'ns' | 'model', title? }]
+```
+
+#### `discoverModels(namespace)` - Find all models recursively
+
+```typescript
+// Discover all available models in a namespace
+const models = await client.discoverModels("datasets/gov/rc/ar");
+console.log(`Found ${models.length} models`);
+
+for (const model of models) {
+  console.log(`${model.path} - ${model.title}`);
+}
+
+// Then generate types for a specific model:
+// npx lt-gen datasets/gov/rc/ar/savivaldybe -o ./types/savivaldybe.d.ts
+```
+
+Returns: `{ path, title?, namespace }[]`
+
+---
+
+## Type Safety & Autocomplete
+
+The SDK provides full TypeScript support. The workflow is:
+
+1. **Generate types** for your dataset:
+
+   ```bash
+   npx lt-gen datasets/gov/rc/ar/savivaldybe -o ./types/savivaldybe.d.ts
+   ```
+
+2. **Import and use** in your code:
+
+   ```typescript
+   import { SpintaClient } from "lt-open-data-sdk";
+   import type { GovRcArSavivaldybe_Savivaldybe } from "./types/savivaldybe";
+
+   const client = new SpintaClient();
+
+   // Pass the type to the method to get full autocomplete!
+   const data = await client.getAll<GovRcArSavivaldybe_Savivaldybe>(
+     "datasets/gov/rc/ar/savivaldybe/Savivaldybe"
+   );
+
+   // ✅ TypeScript knows these fields exist:
+   console.log(data[0].pavadinimas); // string
+   console.log(data[0].sav_kodas); // number
+   ```
+
+---
+
+## Pagination
+
+The API uses cursor-based pagination with `_page.next` tokens.
+
+### Automatic Pagination with `stream()`
+
+Use `stream()` to iterate through all records automatically:
+
+```typescript
+const query = new QueryBuilder().limit(100); // 100 items per page
+
+for await (const item of client.stream("datasets/gov/example/City", query)) {
+  console.log(item.pavadinimas);
+  // Automatically fetches next page when current page is exhausted
+}
+```
+
+**How it works:**
+
+1. Fetches first page with your query
+2. Yields items one by one
+3. When page exhausted, uses `_page.next` token to fetch next page
+4. Continues until no more pages
+
+### Manual Pagination with `getAllRaw()`
+
+For more control, handle pagination yourself:
+
+```typescript
+let pageToken: string | undefined;
+
+do {
+  // Build query with page token
+  let query = new QueryBuilder().limit(100);
+
+  const response = await client.getAllRaw("datasets/gov/example/City", query);
+
+  // Process this page
+  for (const item of response._data) {
+    console.log(item);
+  }
+
+  // Get next page token
+  pageToken = response._page?.next;
+
+  // Note: You need to add page(token) to next request manually
+  // This is handled automatically by stream()
+} while (pageToken);
+```
+
+> **Tip**: Use `stream()` for most cases. Use `getAllRaw()` when you need access to page metadata or custom page handling.
+
+## CLI Type Generator
+
+Generate TypeScript interfaces from live API metadata:
+
+```bash
+# Install globally or use npx
+npx lt-gen datasets/gov/rc/ar/savivaldybe
+
+# Save to file
+npx lt-gen datasets/gov/rc/ar/savivaldybe -o ./types/savivaldybe.d.ts
+
+# Custom API URL
+npx lt-gen datasets/gov/rc/ar/savivaldybe --base-url https://get-test.data.gov.lt
+```
+
+### Generated Output
+
+```typescript
+export interface GovRcArSavivaldybe_Savivaldybe {
+  _id: string;
+  _type: string;
+  _revision?: string;
+  sav_kodas?: number;
+  pavadinimas?: string;
+  apskritis?: string | { _id: string }; // ref type
+  sav_nuo?: string; // date
+}
+
+export interface ModelMap {
+  "datasets/gov/rc/ar/savivaldybe/Savivaldybe": GovRcArSavivaldybe_Savivaldybe;
+}
+```
+
+> **Note**: Types are inferred from data samples since schema endpoints require authentication.
+
+---
+
+## Authentication _(Untested)_
+
+For write operations or private data, provide OAuth credentials:
+
+```typescript
+const client = new SpintaClient({
+  clientId: "your-client-id",
+  clientSecret: "your-client-secret",
+  authUrl: "https://put.data.gov.lt", // optional, default
+  scopes: ["spinta_getone", "spinta_getall"], // optional
+});
+```
+
+The SDK handles:
+
+- OAuth client credentials flow
+- Automatic token caching
+- Token refresh before expiry (5-minute buffer)
+
+> ⚠️ **Note**: Authentication has been implemented but not tested against a live auth server.
+
+---
+
+## Error Handling
+
+```typescript
+import {
+  SpintaError,
+  NotFoundError,
+  AuthenticationError,
+  ValidationError,
+} from "lt-open-data-sdk";
+
+try {
+  const data = await client.getOne("datasets/example", "invalid-id");
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.log("Not found:", error.message);
+  } else if (error instanceof AuthenticationError) {
+    console.log("Auth failed:", error.status);
+  } else if (error instanceof ValidationError) {
+    console.log("Bad request:", error.body);
+  }
+}
+```
+
+---
+
+## API Reference
+
+### Exports
+
+```typescript
+// Client
+export { SpintaClient } from "./client/SpintaClient";
+export {
+  SpintaError,
+  AuthenticationError,
+  NotFoundError,
+  ValidationError,
+} from "./client/errors";
+
+// Query Builder
+export { QueryBuilder } from "./builder/QueryBuilder";
+export { FilterBuilder } from "./builder/FilterBuilder";
+
+// Types
+export type {
+  ClientConfig,
+  SpintaResponse,
+  SpintaObject,
+} from "./client/types";
+```
+
+---
+
+## License
+
+MIT

package/dist/builder/FilterBuilder.d.ts

@@ -0,0 +1,19 @@
+/**
+ * FilterBuilder - Fluent interface for constructing filter expressions
+ *
+ * Supports AND/OR combinations with proper precedence handling.
+ * Per the Spinta grammar, AND binds tighter than OR.
+ * Auto-wraps expressions in parentheses when mixing operators.
+ */
+import type { FilterBuilderInterface, FieldFilterInterface, FilterExpression } from './types.js';
+/**
+ * FilterBuilder - Entry point for constructing filter expressions
+ */
+export declare class FilterBuilder<T> implements FilterBuilderInterface<T> {
+    field(name: keyof T | string): FieldFilterInterface;
+}
+/**
+ * Converts a filter expression tree to a Spinta query string
+ */
+export declare function filterToString(expr: FilterExpression): string;
+//# sourceMappingURL=FilterBuilder.d.ts.map

package/dist/builder/FilterBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilterBuilder.d.ts","sourceRoot":"","sources":["../../src/builder/FilterBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,oBAAoB,EAEpB,gBAAgB,EAGjB,MAAM,YAAY,CAAC;AAsFpB;;GAEG;AACH,qBAAa,aAAa,CAAC,CAAC,CAAE,YAAW,sBAAsB,CAAC,CAAC,CAAC;IAChE,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,oBAAoB;CAGpD;AA6CD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAkD7D"}

package/dist/builder/FilterBuilder.js

@@ -0,0 +1,178 @@
+/**
+ * FilterBuilder - Fluent interface for constructing filter expressions
+ *
+ * Supports AND/OR combinations with proper precedence handling.
+ * Per the Spinta grammar, AND binds tighter than OR.
+ * Auto-wraps expressions in parentheses when mixing operators.
+ */
+/**
+ * Creates a filter expression builder from a filter node
+ */
+function createExpressionBuilder(node) {
+    return {
+        node,
+        and(other) {
+            return createExpressionBuilder({
+                type: 'and',
+                left: this.node,
+                right: other.node,
+            });
+        },
+        or(other) {
+            return createExpressionBuilder({
+                type: 'or',
+                left: this.node,
+                right: other.node,
+            });
+        },
+    };
+}
+/**
+ * Field filter for building comparison expressions
+ */
+class FieldFilter {
+    fieldName;
+    constructor(fieldName) {
+        this.fieldName = fieldName;
+    }
+    comparison(operator, value) {
+        return createExpressionBuilder({
+            type: 'comparison',
+            field: this.fieldName,
+            operator,
+            value,
+        });
+    }
+    stringOp(operator, value) {
+        return createExpressionBuilder({
+            type: 'string_op',
+            field: this.fieldName,
+            operator,
+            value,
+        });
+    }
+    eq(value) {
+        return this.comparison('eq', value);
+    }
+    ne(value) {
+        return this.comparison('ne', value);
+    }
+    lt(value) {
+        return this.comparison('lt', value);
+    }
+    le(value) {
+        return this.comparison('le', value);
+    }
+    gt(value) {
+        return this.comparison('gt', value);
+    }
+    ge(value) {
+        return this.comparison('ge', value);
+    }
+    contains(value) {
+        return this.stringOp('contains', value);
+    }
+    startswith(value) {
+        return this.stringOp('startswith', value);
+    }
+}
+/**
+ * FilterBuilder - Entry point for constructing filter expressions
+ */
+export class FilterBuilder {
+    field(name) {
+        return new FieldFilter(String(name));
+    }
+}
+/**
+ * Formats a value for use in a Spinta query
+ * Values are URL-encoded to ensure safe transport in URLs
+ */
+function formatValue(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'string') {
+        // 1. Escape internal quotes
+        const escaped = value.replace(/"/g, '\\"');
+        // 2. Wrap in quotes
+        const quoted = `"${escaped}"`;
+        // 3. Encode the final token so it survives URL transport
+        return encodeURIComponent(quoted);
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'true' : 'false';
+    }
+    if (typeof value === 'number') {
+        return String(value);
+    }
+    if (value instanceof Date) {
+        // Encode ISO date string for URL safety
+        return encodeURIComponent(`"${value.toISOString()}"`);
+    }
+    // For other objects, use JSON.stringify and encode
+    if (typeof value === 'object') {
+        return encodeURIComponent(JSON.stringify(value));
+    }
+    // For symbols, functions, or other types - stringify safely
+    return encodeURIComponent(`"${typeof value === 'symbol' ? value.toString() : 'unknown'}"`);
+}
+/**
+ * Checks if an expression needs parentheses when used as a child of the given parent type
+ * AND binds tighter than OR, so OR children inside AND need parens
+ */
+function needsParens(child, parentType) {
+    // OR inside AND needs parentheses because AND has higher precedence
+    return parentType === 'and' && child.type === 'or';
+}
+/**
+ * Converts a filter expression tree to a Spinta query string
+ */
+export function filterToString(expr) {
+    switch (expr.type) {
+        case 'comparison': {
+            const value = formatValue(expr.value);
+            // Use operator syntax: field=value, field!=value, etc.
+            switch (expr.operator) {
+                case 'eq':
+                    return `${expr.field}=${value}`;
+                case 'ne':
+                    return `${expr.field}!=${value}`;
+                case 'lt':
+                    return `${expr.field}<${value}`;
+                case 'le':
+                    return `${expr.field}<=${value}`;
+                case 'gt':
+                    return `${expr.field}>${value}`;
+                case 'ge':
+                    return `${expr.field}>=${value}`;
+            }
+            break;
+        }
+        case 'string_op': {
+            const value = formatValue(expr.value);
+            // Use method syntax: field.contains(value)
+            return `${expr.field}.${expr.operator}(${value})`;
+        }
+        case 'and': {
+            const leftStr = needsParens(expr.left, 'and')
+                ? `(${filterToString(expr.left)})`
+                : filterToString(expr.left);
+            const rightStr = needsParens(expr.right, 'and')
+                ? `(${filterToString(expr.right)})`
+                : filterToString(expr.right);
+            return `${leftStr}&${rightStr}`;
+        }
+        case 'or': {
+            const leftStr = needsParens(expr.left, 'or')
+                ? `(${filterToString(expr.left)})`
+                : filterToString(expr.left);
+            const rightStr = needsParens(expr.right, 'or')
+                ? `(${filterToString(expr.right)})`
+                : filterToString(expr.right);
+            return `${leftStr}|${rightStr}`;
+        }
+    }
+    return '';
+}
+//# sourceMappingURL=FilterBuilder.js.map

package/dist/builder/FilterBuilder.js.map

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

package/dist/builder/QueryBuilder.d.ts

@@ -0,0 +1,99 @@
+/**
+ * QueryBuilder - Fluent interface for constructing Spinta DSQL query strings
+ *
+ * @example
+ * ```typescript
+ * const query = new QueryBuilder<City>()
+ *   .select('name', 'population')
+ *   .filter(f => f.field('country').eq('lt'))
+ *   .sort('name')
+ *   .limit(10);
+ *
+ * // Generates: ?select(name,population)&country="lt"&sort(name)&limit(10)
+ * const url = `/datasets/gov/example/City${query.toQueryString()}`;
+ * ```
+ */
+import type { FilterCallback } from './types.js';
+export declare class QueryBuilder<T = Record<string, unknown>> {
+    private selectFields;
+    private sortSpecs;
+    private limitValue;
+    private countMode;
+    private filterExpression;
+    /**
+     * Select specific fields to return
+     *
+     * @example
+     * .select('id', 'name') → ?select(id,name)
+     * .select('country.name') → ?select(country.name) // Supports dot notation for joins
+     */
+    select(...fields: (keyof T | string)[]): this;
+    /**
+     * Sort by field in ascending order
+     *
+     * @example
+     * .sort('name') → ?sort(name)
+     */
+    sort(field: keyof T | string): this;
+    /**
+     * Sort by field in descending order
+     *
+     * @example
+     * .sortDesc('date') → ?sort(-date)
+     */
+    sortDesc(field: keyof T | string): this;
+    /**
+     * Limit the number of results returned
+     *
+     * @example
+     * .limit(10) → ?limit(10)
+     */
+    limit(n: number): this;
+    /**
+     * Request count of objects instead of the objects themselves
+     *
+     * @example
+     * .count() → ?count()
+     */
+    count(): this;
+    /**
+     * Add filter conditions
+     *
+     * @example
+     * // Simple equality
+     * .filter(f => f.field('code').eq('lt'))
+     *
+     * // String operations
+     * .filter(f => f.field('name').contains('Vilnius'))
+     *
+     * // AND combination
+     * .filter(f => f.field('a').eq(1).and(f.field('b').eq(2)))
+     *
+     * // OR combination
+     * .filter(f => f.field('a').eq(1).or(f.field('b').eq(2)))
+     *
+     * // Complex: OR inside AND (auto-wrapped in parens)
+     * .filter(f =>
+     *   f.field('a').eq(1).and(
+     *     f.field('b').eq(2).or(f.field('c').eq(3))
+     *   )
+     * )
+     * // Generates: a=1&(b=2|c=3)
+     */
+    filter(callback: FilterCallback<T>): this;
+    /**
+     * Generate the URL query string
+     *
+     * @returns Query string starting with '?' if there are any parameters, empty string otherwise
+     *
+     * @example
+     * new QueryBuilder().select('name').sort('name').toQueryString()
+     * // Returns: '?select(name)&sort(name)'
+     */
+    toQueryString(): string;
+    /**
+     * Clone this query builder (useful for creating variants)
+     */
+    clone(): QueryBuilder<T>;
+}
+//# sourceMappingURL=QueryBuilder.d.ts.map

package/dist/builder/QueryBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryBuilder.d.ts","sourceRoot":"","sources":["../../src/builder/QueryBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAqC,MAAM,YAAY,CAAC;AAEpF,qBAAa,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACnD,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAwC;IAEhE;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,GAAG,IAAI;IAK7C;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI;IAKnC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI;IAKvC;;;;;OAKG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKtB;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAKb;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAczC;;;;;;;;OAQG;IACH,aAAa,IAAI,MAAM;IAwCvB;;OAEG;IACH,KAAK,IAAI,YAAY,CAAC,CAAC,CAAC;CASzB"}