@scarif/scarif-js 1.0.0

package/README.md

@@ -0,0 +1,451 @@
+# Stoorplek Data API SDK
+
+Simple, type-safe SDK for accessing data from your API service with powerful chainable querying capabilities. Built with Supabase-style select syntax for intuitive querying.
+
+## Installation
+
+```bash
+npm install stoorplek-data-api
+```
+
+## Quick Start
+
+### Option 1: True One-Liner (Environment Variable)
+
+Set your API key in `.env`:
+```env
+MY_API_KEY=sk_live_your_api_key_here
+```
+
+Then use the one-liner:
+```javascript
+import { stoorplek } from 'stoorplek-data-api';
+
+// That's it! One import, one call
+const { data, error } = await stoorplek.from('countries').select('*');
+console.log(data);
+```
+
+### Option 2: Configure Once, Use Everywhere
+
+```javascript
+import { stoorplek } from 'stoorplek-data-api';
+
+// Configure once at app startup
+stoorplek.configure({
+  apiKey: 'sk_live_your_api_key_here'
+});
+
+// Then use anywhere in your app
+const { data: countries } = await stoorplek.from('countries').select('*');
+const { data: cities } = await stoorplek.from('cities').select('*');
+```
+
+### Option 3: Traditional Client (More Control)
+
+```javascript
+import { createClient } from 'stoorplek-data-api';
+
+const client = createClient({
+  apiKey: 'sk_live_your_api_key_here',
+  baseUrl: 'https://api.yourservice.com', // optional
+  timeout: 30000 // optional, defaults to 30 seconds
+});
+
+const { data, error } = await client.from('countries').select('*');
+```
+
+## Features
+
+✨ **Type-Safe** - Full TypeScript support with automatic type inference  
+🔍 **Chainable API** - Supabase-like query builder with fluent interface  
+📦 **Zero Config** - Works with environment variables out of the box  
+🎯 **One-Liner Ready** - Import and use in a single line  
+⚡ **Lightweight** - Minimal dependencies, maximum performance  
+🔗 **Relations** - Easy eager loading of related data
+
+## Querying & Filtering
+
+### Basic Queries
+
+```javascript
+import { stoorplek } from 'stoorplek-data-api';
+
+// Get all records (select is required)
+const { data: all } = await stoorplek.from('countries').select('*');
+
+// Select specific columns
+const { data: names } = await stoorplek.from('countries')
+  .select('name, iso');
+```
+
+### Relations (Eager Loading)
+
+Supabase-style nested relations in the select string:
+
+```javascript
+// Load relations (all columns)
+const { data: withCities } = await stoorplek.from('countries')
+  .select('*, cities(*)');
+
+// Load relations with specific columns
+const { data: custom } = await stoorplek.from('countries')
+  .select('name, iso, cities(id, name, population)');
+
+// Multiple relations
+const { data: multiple } = await stoorplek.from('countries')
+  .select('*, cities(*), languages(*)');
+
+// Multiple relations with column selection
+const { data: complex } = await stoorplek.from('countries')
+  .select('id, name, cities(id, name), languages(*)');
+```
+
+### Filtering
+
+```javascript
+// Equal to
+const { data: usa } = await stoorplek.from('countries')
+  .select('*')
+  .eq('iso', 'US');
+
+// Not equal to
+const { data: notUSA } = await stoorplek.from('countries')
+  .select('*')
+  .neq('iso', 'US');
+
+// Greater than / Less than
+const { data: highIds } = await stoorplek.from('countries')
+  .select('*')
+  .gt('id', 100);
+
+const { data: lowIds } = await stoorplek.from('countries')
+  .select('*')
+  .lt('id', 50);
+
+// Pattern matching (case-insensitive)
+const { data: unitedCountries } = await stoorplek.from('countries')
+  .select('*')
+  .ilike('name', '%united%');
+
+// Pattern matching (case-sensitive)
+const { data: exactMatch } = await stoorplek.from('countries')
+  .select('*')
+  .like('name', 'United%');
+
+// In array
+const { data: specific } = await stoorplek.from('countries')
+  .select('*')
+  .in('iso', ['US', 'CA', 'MX']);
+
+// Not in array
+const { data: excluded } = await stoorplek.from('countries')
+  .select('*')
+  .notIn('iso', ['US', 'CA']);
+
+// Is null / Is not null
+const { data: withNull } = await stoorplek.from('countries')
+  .select('*')
+  .isNull('deleted_at');
+
+const { data: withoutNull } = await stoorplek.from('countries')
+  .select('*')
+  .isNotNull('email');
+```
+
+### Sorting
+
+```javascript
+// Single column sort (ascending by default)
+const { data: sorted } = await stoorplek.from('countries')
+  .select('*')
+  .order('name');
+
+// Descending order
+const { data: sortedDesc } = await stoorplek.from('countries')
+  .select('*')
+  .order('name', 'desc');
+
+// Multiple columns (chain multiple order calls)
+const { data: multiSort } = await stoorplek.from('countries')
+  .select('*')
+  .order('name', 'asc')
+  .order('id', 'desc');
+```
+
+### Pagination
+
+```javascript
+// Limit results
+const { data: limited } = await stoorplek.from('countries')
+  .select('*')
+  .limit(10);
+
+// Offset for pagination
+const { data: page2 } = await stoorplek.from('countries')
+  .select('*')
+  .limit(10)
+  .offset(10);
+
+// Combined with sorting
+const { data: paginatedSorted } = await stoorplek.from('countries')
+  .select('*')
+  .order('name')
+  .limit(20)
+  .offset(0);
+```
+
+### Complex Queries
+
+Combine multiple filters for powerful queries:
+
+```javascript
+const { data, error } = await stoorplek.from('countries')
+  .select('name, iso, cities(id, name), languages(*)')
+  .ilike('name', '%united%')
+  .order('name', 'asc')
+  .limit(10);
+```
+
+### Getting Single Result
+
+```javascript
+// Get single result (automatically limits to 1)
+const { data: usa, error } = await stoorplek.from('countries')
+  .select('*')
+  .eq('iso', 'US')
+  .single();
+```
+
+## TypeScript Support
+
+The SDK provides full type safety with automatic type inference:
+
+```typescript
+import { stoorplek } from 'stoorplek-data-api';
+
+// TypeScript automatically knows this returns ApiResponse<Country[]>
+const { data, error } = await stoorplek.from('countries').select('*');
+
+// Full autocomplete and type checking
+data?.forEach(country => {
+  console.log(country.name); // ✅ TypeScript knows 'name' exists
+  console.log(country.iso);  // ✅ TypeScript knows 'iso' exists
+});
+```
+
+### Custom Types
+
+For dynamic tables or custom type definitions:
+
+```typescript
+interface CustomType {
+  id: number;
+  customField: string;
+}
+
+const { data, error } = await stoorplek.from<CustomType>('custom_table').select('*');
+// data is typed as CustomType[] | null
+```
+
+## Error Handling
+
+```javascript
+import { stoorplek } from 'stoorplek-data-api';
+
+const { data, error } = await stoorplek.from('countries')
+  .select('*')
+  .eq('iso', 'US');
+
+if (error) {
+  console.error('API Error:', error.message);
+  console.error('Error Code:', error.code);
+} else {
+  console.log('Data:', data);
+}
+```
+
+## API Reference
+
+### `createClient(options)`
+
+Creates a new API client instance.
+
+**Parameters:**
+- `options.apiKey` (required): Your API key
+- `options.baseUrl` (optional): Base URL for the API (defaults to http://localhost:3000)
+- `options.timeout` (optional): Request timeout in milliseconds (defaults to 30000)
+
+**Returns:** `ApiClient` instance
+
+**Example:**
+```javascript
+const client = createClient({
+  apiKey: 'sk_live_your_api_key',
+  baseUrl: 'https://api.yourservice.com',
+  timeout: 30000
+});
+```
+
+### `configure(options)`
+
+Configure the default client for one-liner usage.
+
+**Parameters:**
+- `options.apiKey` (required): Your API key
+- `options.baseUrl` (optional): Base URL for the API
+- `options.timeout` (optional): Request timeout in milliseconds
+
+**Example:**
+```javascript
+import { configure } from 'stoorplek-data-api';
+
+configure({ 
+  apiKey: process.env.MY_API_KEY,
+  timeout: 30000
+});
+```
+
+### `from(table)` / `query(table)`
+
+Start a chainable query for a specific table.
+
+**Parameters:**
+- `table`: Name of the table to query
+
+**Returns:** `QueryBuilder<T>` instance with chainable methods
+
+**Chainable Methods:**
+- `.select(query)` - **Required.** Select columns and relations using Supabase-style syntax (e.g., `'id, name, cities(id, name)'`)
+- **Filters:** `.eq()`, `.neq()`, `.gt()`, `.gte()`, `.lt()`, `.lte()`, `.like()`, `.ilike()`, `.in()`, `.notIn()`, `.isNull()`, `.isNotNull()` - See [Filtering](#filtering) section for examples
+- `.order(column, direction?)` - Sort (direction: 'asc' | 'desc', defaults to 'asc')
+- `.limit(count)` - Limit results
+- `.offset(count)` - Pagination offset
+- `.range(from, to)` - Set offset and limit together
+- `.single()` - Execute query and return single result (returns object instead of array)
+
+**Example:**
+```javascript
+const { data, error } = await stoorplek.from('countries')
+  .select('name, iso, cities(id, name)')
+  .ilike('name', '%united%')
+  .order('name', 'asc')
+  .limit(10);
+```
+
+### `health()`
+
+Check if the API is healthy.
+
+**Returns:** `Promise<ApiResponse>`
+
+**Example:**
+```javascript
+import { health } from 'stoorplek-data-api';
+
+const status = await health();
+console.log(status);
+```
+
+### `stoorplek`
+
+Default export object for easy importing and usage.
+
+**Example:**
+```javascript
+const { stoorplek } = require('stoorplek-data-api');
+
+// Configure (or use MY_API_KEY env var)
+stoorplek.configure({ apiKey: 'your-key' });
+
+// Use in queries
+const { data, error } = await stoorplek.from('countries').select('*');
+```
+
+## Response Format
+
+All API responses follow this structure:
+
+```typescript
+interface ApiResponse<T> {
+  data: T;
+  error: {
+    message: string;
+    code?: string;
+    details?: any;
+  } | null;
+  status: number;
+}
+```
+
+**Example success response:**
+```json
+{
+  "data": [
+    { "id": 1, "name": "United States", "iso": "US" },
+    { "id": 2, "name": "Canada", "iso": "CA" }
+  ],
+  "error": null,
+  "status": 200
+}
+```
+
+**Example error response:**
+```json
+{
+  "data": [],
+  "error": {
+    "message": "Invalid table name",
+    "code": "INVALID_TABLE",
+    "details": {}
+  },
+  "status": 400
+}
+```
+
+## Advanced Usage
+
+### Using with the Client Instance
+
+```javascript
+import { createClient } from 'stoorplek-data-api';
+
+const client = createClient({
+  apiKey: process.env.API_KEY
+});
+
+// All the same chainable methods work
+const { data, error } = await client
+  .from('countries')
+  .select('name, iso')
+  .ilike('name', '%united%');
+```
+
+### Environment Variables
+
+The SDK automatically looks for `MY_API_KEY` in your environment:
+
+```env
+# .env file
+MY_API_KEY=sk_live_your_api_key_here
+```
+
+Then just import and use:
+```javascript
+import { stoorplek } from 'stoorplek-data-api';
+
+const { data, error } = await stoorplek.from('countries').select('*'); // No configuration needed!
+```
+
+## Available Tables
+
+Currently supported tables:
+- `countries` - Country data with relations to `cities` and `languages`
+- `cities` - City data with relation to `country`
+- `languages` - Language data with relation to `countries`
+
+More tables will be added as the API expands.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import { ApiClientOptions, ApiResponse, QueryBuilder, TableTypes } from './types';
+/**
+ * Main API client class
+ */
+export declare class ApiClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    constructor(options: ApiClientOptions);
+    /**
+     * Start a chainable query for a table
+     *
+     * @example
+     * ```typescript
+     * const countries = await client
+     *   .from('countries')
+     *   .select('name, iso, cities(id, name, population)')
+     *   .ilike('name', '%united%')
+     *   .order('name', 'asc')
+     *   .limit(10);
+     * ```
+     */
+    from<T extends keyof TableTypes>(table: T): QueryBuilder<TableTypes[T]>;
+    from<T = any>(table: string): QueryBuilder<T>;
+    /**
+     * Handles common error cases and returns appropriate ApiResponse
+     */
+    private handleError;
+    private executeQuery;
+    health(): Promise<ApiResponse>;
+    private validateTable;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAc,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAK9F;;GAEG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,gBAAgB;IAcrC;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,UAAU,EAAE,KAAK,EAAE,CAAC,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACvE,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC;IAa7C;;OAEG;IACH,OAAO,CAAC,WAAW;YA4BL,YAAY;IA6DpB,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC;IAsCpC,OAAO,CAAC,aAAa;CAOxB"}

package/dist/client.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiClient = void 0;
+const api_1 = require("./types/api");
+const constants_1 = require("./constants");
+const query_builder_1 = require("./utils/query-builder");
+/**
+ * Main API client class
+ */
+class ApiClient {
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl || constants_1.DEFAULT_BASE_URL;
+        this.timeout = options.timeout || constants_1.DEFAULT_TIMEOUT;
+        if (!this.apiKey) {
+            throw new Error('API key is required');
+        }
+    }
+    from(table) {
+        this.validateTable(table);
+        return new query_builder_1.QueryBuilderImpl(table, (t, state) => this.executeQuery(t, state));
+    }
+    // ===========================================
+    // ERROR HANDLING
+    // ===========================================
+    /**
+     * Handles common error cases and returns appropriate ApiResponse
+     */
+    handleError(error, defaultMessage, defaultData) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            return {
+                data: defaultData,
+                error: {
+                    message: `Request timeout after ${this.timeout}ms`,
+                    code: 'TIMEOUT',
+                },
+                status: 408,
+            };
+        }
+        const errorMessage = error instanceof Error ? error.message : defaultMessage;
+        return {
+            data: defaultData,
+            error: {
+                message: errorMessage,
+                code: 'FETCH_ERROR',
+                details: error,
+            },
+            status: 0,
+        };
+    }
+    // ===========================================
+    // DIRECT EXECUTION (Internal)
+    // ===========================================
+    async executeQuery(table, state) {
+        const queryString = (0, query_builder_1.buildQueryString)(state);
+        const url = `${this.baseUrl}/data/${table}${queryString}`;
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            const jsonData = await response.json();
+            if (!response.ok) {
+                const errorData = (0, api_1.isApiErrorResponse)(jsonData) ? jsonData : {};
+                return {
+                    data: [],
+                    error: {
+                        message: errorData.message || 'Request failed',
+                        code: errorData.code,
+                        details: errorData.details,
+                    },
+                    status: response.status,
+                };
+            }
+            if ((0, api_1.isApiSuccessResponse)(jsonData)) {
+                return {
+                    data: jsonData.data,
+                    error: null,
+                    status: response.status,
+                };
+            }
+            // Fallback for unexpected response structure
+            return {
+                data: [],
+                error: {
+                    message: 'Unexpected response format',
+                    code: 'INVALID_RESPONSE',
+                    details: jsonData,
+                },
+                status: response.status,
+            };
+        }
+        catch (error) {
+            return this.handleError(error, 'Unknown error occurred', []);
+        }
+    }
+    // ===========================================
+    // HEALTH CHECK
+    // ===========================================
+    async health() {
+        const url = `${this.baseUrl}/health`;
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                },
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            const data = await response.json();
+            return {
+                data,
+                error: null,
+                status: response.status,
+            };
+        }
+        catch (error) {
+            const response = this.handleError(error, 'Health check failed', null);
+            // Override error code for health check
+            return {
+                ...response,
+                error: response.error ? { ...response.error, code: 'HEALTH_CHECK_ERROR' } : null,
+            };
+        }
+    }
+    // ===========================================
+    // VALIDATION
+    // ===========================================
+    validateTable(table) {
+        if (!constants_1.ALLOWED_TABLES[table]) {
+            throw new Error(`Invalid table: "${table}". Allowed tables: ${Object.keys(constants_1.ALLOWED_TABLES).join(', ')}`);
+        }
+    }
+}
+exports.ApiClient = ApiClient;

package/dist/constants.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Package constants and configuration
+ */
+/**
+ * List of allowed table names
+ * This should match your server's whitelist
+ */
+export interface TableDefinition {
+    relations?: string[];
+}
+export declare const ALLOWED_TABLES: Record<string, TableDefinition>;
+/**
+ * Type for allowed table names
+ */
+export type AllowedTable = keyof typeof ALLOWED_TABLES;
+/**
+ * Default API base URL
+ */
+export declare const DEFAULT_BASE_URL = "http://localhost:3000";
+/**
+ * Environment variable name for API key
+ */
+export declare const API_KEY_ENV_VAR = "MY_API_KEY";
+export declare const DEFAULT_TIMEOUT = 30000;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAU1D,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,cAAc,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,eAAe,eAAe,CAAC;AAE5C,eAAO,MAAM,eAAe,QAAQ,CAAC"}

package/dist/constants.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Package constants and configuration
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TIMEOUT = exports.API_KEY_ENV_VAR = exports.DEFAULT_BASE_URL = exports.ALLOWED_TABLES = void 0;
+exports.ALLOWED_TABLES = {
+    countries: {
+        relations: ['cities', 'languages']
+    },
+    cities: {
+        relations: ['country']
+    },
+    languages: {
+        relations: ['countries']
+    }
+};
+/**
+ * Default API base URL
+ */
+exports.DEFAULT_BASE_URL = 'http://localhost:3000';
+/**
+ * Environment variable name for API key
+ */
+exports.API_KEY_ENV_VAR = 'MY_API_KEY';
+exports.DEFAULT_TIMEOUT = 30000; // 30 seconds