kodzero-front-sdk-alfa 0.0.2

package/.eslintrc.cjs

@@ -0,0 +1,13 @@
+module.exports = {
+    "env": {
+        "browser": true,
+        "es2021": true
+    },
+    "extends": "eslint:recommended",
+    "parserOptions": {
+        "ecmaVersion": "latest",
+        "sourceType": "module"
+    },
+    "rules": {
+    }
+}

package/.eslintrc.json

@@ -0,0 +1,16 @@
+{
+    "env": {
+        "browser": true,
+        "commonjs": true,
+        "es2021": true,
+        "node": true
+    },
+    "extends": [
+        "eslint:recommended"
+    ],
+    "parserOptions": {
+        "ecmaVersion": 12
+    },
+    "rules": {
+    }
+}

package/README.md

@@ -0,0 +1,313 @@
+# Kodzero Frontend SDK [alfa]
+
+A lightweight OOP library for frontend applications to easily interact with Kodzero backend APIs. This SDK provides a clean, object-oriented approach for working with your backend data models and authentication.
+
+## Installation
+
+```bash
+npm install kodzero-front-sdk-alfa
+```
+```
+
+## Authentication
+
+The SDK provides built-in authentication features:
+
+```javascript
+// Initialize the SDK with your backend URL
+const kodzero = new Kodzero({
+  host: 'https://api.your-backend.com'
+});
+
+// Sign up a new user
+const signupResult = await kodzero.auth.signup({
+  email: 'user@example.com',
+  password: 'secure_password'
+});
+
+// Sign in
+const signinResult = await kodzero.auth.signin({
+  email: 'user@example.com',
+  password: 'secure_password'
+});
+
+// Verify current authentication status
+const verified = await kodzero.auth.verify();
+
+// Refresh the token
+const refreshed = await kodzero.auth.refresh();
+
+// Sign out
+await kodzero.auth.signout();
+
+// Manually set tokens (useful for persisting sessions)
+kodzero.auth.setTokens('access_token', 'refresh_token');
+
+// Clear tokens
+kodzero.auth.clearTokens();
+```
+
+## Model
+
+Creating and using models is the core functionality of the SDK. Models provide an OOP approach to interacting with your backend data.
+
+### Creating a Model
+
+```javascript
+import Schema from 'validno';
+
+// Define your data model interface
+interface User {
+  _id?: string;
+  name: string;
+  email: string;
+  createdAt?: Date;
+}
+
+// Optional: Create a schema for validation
+const userSchema = new Schema({
+  _id: { type: String },
+  name: { type: String },
+  email: { type: String },
+  createdAt: { type: Date }
+});
+
+// Create a model for the 'users' collection
+const User = kodzero.createModel<User>({
+  collection: 'users',
+  schema: userSchema // Optional but recommended for validation
+});
+```
+
+### Instance Methods
+
+After creating a model, you can use its instance methods to work with individual records:
+
+```javascript
+// Create a new user instance
+const newUser = new User({
+  name: 'John Doe',
+  email: 'john@example.com'
+});
+
+// Save the new user to the database (creates a new record)
+await newUser.save();
+console.log('New user ID:', newUser.data()._id);
+
+// Get the current data
+const userData = newUser.data();
+
+// Update user data with the set method
+newUser.set('name', 'Jane Doe');
+// Or with object syntax for multiple fields
+newUser.set({
+  name: 'Jane Doe',
+  email: 'jane@example.com'
+});
+
+// Update the record in the database
+await newUser.update();
+
+// Or use save() which handles both create and update
+await newUser.save();
+
+// Validate the data against the schema
+const validationResult = newUser.validate();
+if (!validationResult.ok) {
+  console.error('Validation errors:', validationResult.joinErrors());
+}
+
+// Delete the user from the database
+await newUser.delete();
+```
+
+## Advanced Model Usage
+
+### Custom Methods
+
+You can extend your models with custom methods:
+
+```javascript
+// Define your model interface
+interface Car {
+  _id?: string;
+  make: string;
+  model: string;
+  year: number;
+}
+
+// Define custom methods interface
+interface CarMethods {
+  getDescription: () => string;
+  isVintage: () => boolean;
+}
+
+// Create the model with the custom methods type
+const Car = kodzero.createModel<Car, CarMethods>({
+  collection: 'cars',
+  schema: carSchema
+});
+
+// Register custom methods
+Car.registerMethod('getDescription', function() {
+  const data = this.data();
+  return `${data.make} ${data.model} (${data.year})`;
+});
+
+Car.registerMethod('isVintage', function() {
+  return this.data().year < 1980;
+});
+
+// Usage
+const myCar = await Car.get('car_id_here');
+console.log(myCar.getDescription());  // "Toyota Corolla (2020)"
+console.log(myCar.isVintage());       // false
+```
+
+## Static Model Operations
+
+Models provide static methods for working with collections as a whole:
+
+### Fetching Data
+
+```javascript
+// Find a document and return plain data (not an instance)
+const userData = await User.find('user_id_here');
+
+// Find multiple documents with optional query parameters
+const users = await User.findMany({
+  page: 1,           // Pagination: page number
+  perPage: 10,       // Items per page
+  search: 'John',    // Search term
+  sort: '-createdAt', // Sort by field (prefix with - for descending)
+  fields: ['name', 'email'] // Specific fields to return
+});
+
+// Create a single document
+const newUser = await User.create({
+  name: 'Alice',
+  email: 'alice@example.com'
+});
+
+// Update a single document by ID
+const updatedUser = await User.update('user_id', {
+  name: 'Updated Name'
+});
+
+// Delete a document by ID
+const deleted = await User.delete('user_id');
+
+// Get distinct values
+const distinctNames = await User.distinct(['name']);
+```
+
+### Batch Operations
+
+The SDK supports batch operations for improved efficiency:
+
+```javascript
+// Create multiple records at once
+const newUsers = await User.createMany([
+  { name: 'John', email: 'john@example.com' },
+  { name: 'Jane', email: 'jane@example.com' }
+]);
+
+// Update multiple records
+const updates = await User.updateMany([
+  { _id: 'id1', name: 'Updated Name 1' },
+  { _id: 'id2', email: 'updated2@example.com' }
+]);
+
+// Delete multiple records
+const deleteResults = await User.deleteMany(['id1', 'id2', 'id3']);
+```
+
+## Validation
+
+The SDK uses the `validno` library for schema-based validation. When creating a model with a schema, you can validate your data:
+
+```javascript
+// Define a schema with validation rules
+const carSchema = new Schema({
+  _id: { type: String },
+  make: { type: String, required: true },
+  model: { type: String, required: true },
+  year: { type: Number, min: 1900, max: 2100 }
+});
+
+const Car = kodzero.createModel<Car>({
+  collection: 'cars',
+  schema: carSchema
+});
+
+const car = new Car({
+  make: 'Toyota',
+  // Missing required 'model' field will be caught
+});
+
+const validationResult = car.validate();
+if (!validationResult.ok) {
+  console.error('Validation failed:', validationResult.joinErrors());
+  // Output: "Validation failed: model is required"
+}
+```
+
+## Working with Nested Data
+
+You can easily work with nested data structures:
+
+```javascript
+// Create a model with nested data
+interface Profile {
+  _id?: string;
+  user: {
+    name: string;
+    contact: {
+      email: string;
+      phone?: string;
+    }
+  }
+}
+
+const Profile = kodzero.createModel<Profile>({
+  collection: 'profiles'
+});
+
+const profile = new Profile({
+  user: {
+    name: 'John Doe',
+    contact: {
+      email: 'john@example.com'
+    }
+  }
+});
+
+// Set nested properties
+profile.set('user.contact.phone', '123-456-7890');
+
+// Or with object syntax for multiple nested properties
+profile.set({
+  'user.name': 'Jane Doe',
+  'user.contact.email': 'jane@example.com'
+});
+
+await profile.save();
+```
+
+## Error Handling
+
+The SDK provides proper error handling for API requests:
+
+```javascript
+try {
+  const user = await User.get('non_existent_id');
+} catch (error) {
+  if (error.name === 'KodzeroApiError') {
+    console.error('API Error:', error.message, error.status);
+  } else if (error.name === 'KodzeroValidationError') {
+    console.error('Validation Error:', error.message);
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```

package/dist/Kodzero.d.ts

@@ -0,0 +1,33 @@
+import FluidFetch from "fluid-fetch";
+import { KodzeroAuth } from "./auth/index.js";
+import { ModelOptions } from "./model/BaseModel.js";
+import { TokensManagerClass } from "./auth/tokens.js";
+interface Options {
+    host: string;
+}
+declare class Kodzero {
+    host: string;
+    auth: KodzeroAuth;
+    tokensManager: TokensManagerClass;
+    api: typeof FluidFetch;
+    constructor(options: Options);
+    createModel: <T extends {
+        _id?: string;
+    }, M = {}>(options: Omit<ModelOptions, "host">) => {
+        new (data: T): import("./model/BaseModel.js").default<T> & M;
+        get(id: string): Promise<import("./model/BaseModel.js").default<T> & M>;
+        registerMethod<K extends keyof M>(name: K, fn: M[K]): void;
+        find(id: string): Promise<T>;
+        findMany(options?: import("./model/createModel.js").FindManyOptions | {}): Promise<T[]>;
+        create(data: T): Promise<T>;
+        createMany(data: T[]): Promise<T[]>;
+        update(id: string, data: Partial<T>): Promise<T>;
+        updateMany(updates: Partial<T>[]): Promise<T[]>;
+        delete(id: string): Promise<boolean>;
+        deleteMany(ids: string[]): Promise<Record<string, boolean>>;
+        distinct(fields: string[], filter?: Record<string, any>): Promise<string[]>;
+        host: string;
+        collection: string;
+    };
+}
+export default Kodzero;

package/dist/Kodzero.js

@@ -0,0 +1,22 @@
+import FluidFetch from "fluid-fetch";
+import { KodzeroAuth } from "./auth/index.js";
+import createModel from "./model/createModel.js";
+import { TokensManagerClass } from "./auth/tokens.js";
+class Kodzero {
+    constructor(options) {
+        this.createModel = (options) => {
+            return createModel(Object.assign(Object.assign({}, options), { host: this.host }), this.api);
+        };
+        this.tokensManager = new TokensManagerClass('', '');
+        this.host = options.host;
+        this.api = new FluidFetch();
+        this.auth = new KodzeroAuth({ host: options.host }, this.api, this.tokensManager);
+        this.api.middlewares.request.use((req) => {
+            const accessToken = this.tokensManager.access;
+            if (accessToken)
+                req.headers['Authorization'] = accessToken;
+            return req;
+        });
+    }
+}
+export default Kodzero;

package/dist/auth/base.d.ts

@@ -0,0 +1,15 @@
+import FluidFetch from "fluid-fetch";
+import { AuthOptions } from "./index.js";
+import { TokensManagerClass } from "./tokens.js";
+export declare class KodzeroAuthBase {
+    host: string;
+    api: typeof FluidFetch;
+    tokensManager: TokensManagerClass;
+    constructor(options: AuthOptions, api: typeof FluidFetch, tokensManager: TokensManagerClass);
+    _handleApiError(response: Response): Promise<void>;
+    signin: (...args: any[]) => Promise<any> | void;
+    signup: (...args: any[]) => Promise<any> | void;
+    refresh: (...args: any[]) => Promise<any> | void;
+    signout: (...args: any[]) => Promise<any> | void;
+    verify: (...args: any[]) => Promise<any> | void;
+}

package/dist/auth/base.js

@@ -0,0 +1,18 @@
+import BaseAuthSchema from "../schemas/baseAuth.js";
+import validateApiResponse from "../utils/validateApiResponse.js";
+export class KodzeroAuthBase {
+    constructor(options, api, tokensManager) {
+        this.signin = (...args) => { };
+        this.signup = (...args) => { };
+        this.refresh = (...args) => { };
+        this.signout = (...args) => { };
+        this.verify = (...args) => { };
+        BaseAuthSchema.validateOrThrow(options);
+        this.host = options.host;
+        this.api = api;
+        this.tokensManager = tokensManager;
+    }
+    _handleApiError(response) {
+        return validateApiResponse(response);
+    }
+}

package/dist/auth/email.d.ts

@@ -0,0 +1,23 @@
+import FluidFetch from "fluid-fetch";
+import { AuthOptions } from "./index.js";
+import { KodzeroAuthBase } from "./base.js";
+import { TokensManagerClass } from "./tokens.js";
+interface KodzeroAuthEmailSignin {
+    email: string;
+    password: string;
+}
+declare class KodzeroAuthEmail extends KodzeroAuthBase {
+    tokensManager: TokensManagerClass;
+    collection: "auth/password";
+    constructor(options: AuthOptions, api: typeof FluidFetch, tokensManager: TokensManagerClass);
+    _setTokens: (access: string, refresh?: string) => void;
+    signin: (input: KodzeroAuthEmailSignin) => Promise<{
+        access: string;
+        refresh: string;
+    }>;
+    signup: (userData: Record<string, string>) => Promise<Record<string, any>>;
+    verify: () => Promise<any>;
+    refresh: () => Promise<any>;
+    signout: () => Promise<any>;
+}
+export default KodzeroAuthEmail;

package/dist/auth/email.js

@@ -0,0 +1,70 @@
+import { KodzeroAuthBase } from "./base.js";
+import buildURL from "../utils/buildURL_rename.js";
+class KodzeroAuthEmail extends KodzeroAuthBase {
+    constructor(options, api, tokensManager) {
+        super(options, api, tokensManager);
+        this._setTokens = (access, refresh) => {
+            this.tokensManager.setAccess(access);
+            if (refresh)
+                this.tokensManager.setRefresh(refresh);
+        };
+        this.signin = async (input) => {
+            const url = buildURL(this.host, this.collection + '/signin');
+            const response = await this.api.post(url, input)
+                .headers({ 'Content-Type': 'application/json' });
+            await this._handleApiError(response);
+            const json = await response.json();
+            if (json.ok && json.tokens && json.tokens.access && json.tokens.refresh) {
+                this._setTokens(json.tokens.access, json.tokens.refresh);
+            }
+            return json.tokens;
+        };
+        this.signup = async (userData) => {
+            const url = buildURL(this.host, this.collection + '/signup');
+            const response = await this.api.post(url, userData)
+                .headers({ 'Content-Type': 'application/json' });
+            await this._handleApiError(response);
+            const json = await response.json();
+            if (json.ok && json.result && json.result.tokens.access && json.result.tokens.refresh) {
+                this._setTokens(json.result.tokens.access, json.result.tokens.refresh);
+            }
+            return json.result.user;
+        };
+        this.verify = async () => {
+            try {
+                const url = buildURL(this.host, this.collection + '/verify');
+                const response = await this.api.get(url);
+                const json = await response.json();
+                return json.ok ? true : false;
+            }
+            catch (error) {
+                console.warn("Token verification error:", error);
+                return false;
+            }
+        };
+        this.refresh = async () => {
+            const url = buildURL(this.host, this.collection + '/refresh');
+            const response = await this.api.post(url, { refresh: this.tokensManager.refresh })
+                .headers({ 'Content-Type': 'application/json' });
+            await this._handleApiError(response);
+            const json = await response.json();
+            if (json.ok && json.tokens && json.tokens.access) {
+                this.tokensManager.setAccess(json.tokens.access);
+            }
+            return json.ok ? true : false;
+        };
+        this.signout = async () => {
+            const url = buildURL(this.host, this.collection + '/signout');
+            const response = await this.api.post(url, {})
+                .headers({ 'Content-Type': 'application/json' });
+            await this._handleApiError(response);
+            const json = await response.json();
+            if (json.ok)
+                this.tokensManager.clear();
+            return json.ok ? true : false;
+        };
+        this.tokensManager = tokensManager;
+        this.collection = "auth/password";
+    }
+}
+export default KodzeroAuthEmail;

package/dist/auth/index.d.ts

@@ -0,0 +1,13 @@
+import FluidFetch from "fluid-fetch";
+import { KodzeroAuthBase } from "./base.js";
+import KodzeroAuthEmail from "./email.js";
+import { TokensManagerClass } from "./tokens.js";
+export interface AuthOptions {
+    host: string;
+}
+export declare class KodzeroAuth extends KodzeroAuthBase {
+    email: KodzeroAuthEmail;
+    setTokens: (access: string, refresh?: string) => void;
+    clearTokens: () => void;
+    constructor(options: AuthOptions, api: typeof FluidFetch, tokensManager: TokensManagerClass);
+}

package/dist/auth/index.js

@@ -0,0 +1,21 @@
+import { KodzeroAuthBase } from "./base.js";
+import KodzeroAuthEmail from "./email.js";
+export class KodzeroAuth extends KodzeroAuthBase {
+    constructor(options, api, tokensManager) {
+        super(options, api, tokensManager);
+        this.email = new KodzeroAuthEmail(options, api, tokensManager);
+        this.signin = this.email.signin;
+        this.signup = this.email.signup;
+        this.signout = this.email.signout;
+        this.verify = this.email.verify;
+        this.refresh = this.email.refresh;
+        this.setTokens = (access, refresh) => {
+            tokensManager.setAccess(access);
+            if (refresh)
+                tokensManager.setRefresh(refresh);
+        };
+        this.clearTokens = () => {
+            tokensManager.clear();
+        };
+    }
+}

package/dist/auth/tokens.d.ts

@@ -0,0 +1,10 @@
+export declare class TokensManagerClass {
+    access: string;
+    refresh: string;
+    constructor(access?: string, refresh?: string);
+    hasAccess(): boolean | "";
+    hasRefresh(): boolean | "";
+    setAccess(token: string): void;
+    setRefresh(token: string): void;
+    clear(): void;
+}

package/dist/auth/tokens.js

@@ -0,0 +1,22 @@
+export class TokensManagerClass {
+    constructor(access = '', refresh = '') {
+        this.access = access;
+        this.refresh = refresh;
+    }
+    hasAccess() {
+        return this.access && this.access !== '';
+    }
+    hasRefresh() {
+        return this.refresh && this.refresh !== '';
+    }
+    setAccess(token) {
+        this.access = token;
+    }
+    setRefresh(token) {
+        this.refresh = token;
+    }
+    clear() {
+        this.access = '';
+        this.refresh = '';
+    }
+}

package/dist/errors/KodzeroApiError.d.ts

@@ -0,0 +1,7 @@
+declare class KodzeroApiError extends Error {
+    url: string;
+    statusCode: number;
+    details: string;
+    constructor(url: string, statusCode: number, message: string, details?: string);
+}
+export default KodzeroApiError;

package/dist/errors/KodzeroApiError.js

@@ -0,0 +1,10 @@
+class KodzeroApiError extends Error {
+    constructor(url, statusCode, message, details) {
+        super(message);
+        this.name = "KodzeroApiError";
+        this.url = url;
+        this.statusCode = statusCode;
+        this.details = details || '';
+    }
+}
+export default KodzeroApiError;

package/dist/errors/KodzeroValidationError.d.ts

@@ -0,0 +1,5 @@
+declare class KodzeroValidationError extends Error {
+    errors: string[];
+    constructor(message: string, errors?: string[]);
+}
+export default KodzeroValidationError;

package/dist/errors/KodzeroValidationError.js

@@ -0,0 +1,8 @@
+class KodzeroValidationError extends Error {
+    constructor(message, errors = []) {
+        super(message);
+        this.name = "KodzeroValidationError";
+        this.errors = errors;
+    }
+}
+export default KodzeroValidationError;

package/dist/fetcher/InterceptorManager.d.ts

@@ -0,0 +1,9 @@
+declare class MiddlewareManager<T> {
+    private handlers;
+    private idCounter;
+    use(fulfilled: (value: T) => Promise<T> | T, rejected?: (error: any) => any): number;
+    eject(id: number): void;
+    clear(): void;
+    runMiddlewares(value: T): Promise<T>;
+}
+export default MiddlewareManager;