@heliyos/heliyos-api-core 1.0.1 → 1.0.2

package/.env

@@ -1 +1 @@
-HELIYOS_NPM_TOKEN=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
+NPM_TOKEN=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

package/README.md

@@ -1,400 +1,322 @@
 # @heliyos/heliyos-api-core
 
-This repository is for Heliyos's core api functions and middlewares. Its a private package hosted on npm.
+This repository contains Heliyos's core API functions and middlewares. It's a private package hosted on npm.
 
-# Table of contents
+# Table of Contents
 
-- [NPM config](#npm-config)
-- [Database access](#database-access)
-- [Install](#install)
-  - [Setup app](#setup-app)
-  - [Run app](#run-app)
-- [Options](#options)
-  - [heliyos_app](#heliyos_app)
-- [Modules](#modules)
-  - [Knex paginate method](#knex-paginate-method)
-  - [validate](#validate)
-  - [authentication env vars](#authentication-env-vars)
-  - [axios env vars](#axios-env-vars)
+- [Installation](#installation)
+- [Core Modules](#core-modules)
+  - [App Configuration](#app-configuration)
+  - [Authentication](#authentication)
+  - [Authorization](#authorization)
+  - [Axios HTTP Client](#axios-http-client)
+  - [Database (Knex)](#database-knex)
+  - [Validation](#validation)
+  - [Redis Client](#redis-client)
+  - [Pusher](#pusher)
+  - [SQS (Message Queue)](#sqs-message-queue)
+  - [Email Services](#email-services)
+  - [Environment Management](#environment-management)
+  - [Logging](#logging)
+- [Development](#development)
+- [Publishing](#publishing)
 
-# NPM config
+# Installation
 
-## 1. Add .npmrc file
+1. Add `.npmrc` file in your project root:
 
-Create a `.npmrc` file in project root and add this:
-
-```
-//registry.npmjs.org/:_authToken=${NPM_TOKEN}
-```
-
-Next, add `NPM_TOKEN` as an environment variable.
-
-## 2 (a). Local usage
-
-Export the `NPM_TOKEN` value to your bash environment
-
-### Linux / Mac
-
-Add this to your `~/.bash_profile` or `~/.zshrc`
-
-```
-export NPM_TOKEN="token-goes-here"
 ```
-
-Reload bash by running
-
-```
-source ~/.bash_profile
+registry.npmjs.org/:_authToken=${NPM_TOKEN}
 ```
 
-### Windows
+2. Install the package:
 
-Running the following:
-
-```
-setx NPM_TOKEN token-goes-here
+```bash
+npm install @heliyos/heliyos-api-core
 ```
 
-Reload terminal
-
-## 2 (b). Remote usage: Heroku, AWS, etc
-
-Add `NPM_TOKEN` to your env vars.
-
-# Install
-
-Run `npm i --save @heliyos/heliyos-api-core`
-
-## Setup app
+# Core Modules
 
-Create `app.js` or `app.ts` file in root or /src directory, respectively.
+## App Configuration
 
-## TypeScript
+The core app setup provides middleware configuration and error handling.
 
 ```typescript
-// File: src/app.ts
+import { core_app } from "@heliyos/heliyos-api-core";
+import userRoutes from "./routes/user";
 
-// Import style in typescript
-import { heliyos_app } from "@heliyos/heliyos-api-core";
+const routes = [userRoutes];
 
-// Get all routes
-import user_routes from "./routes/v1/user/user_routes";
-
-const routes = [user_routes];
-
-//
-// Configure options (optional)
-// If true, you must create a /static dir in root.
-// If you prefer no static directory, do not specify
-// a staticDir in options or set it to false.
-//
 const options = {
-  staticDir: true,
+  staticDir: true, // Enable static file serving
+  skipExternals: false, // Skip external middleware
+  skipInternals: false, // Skip internal middleware
+  excludedHeaderRegexString: "", // Regex for excluding headers
 };
 
-// Start app
 const app = express();
-heliyos_app(app, routes, options);
-```
-
-Importing specific modules:
-
-```typescript
-import { heliyos_app, knex } from '@heliyos/heliyos-api-core';
-
-await knex(...);
+await core_app(app, routes, options);
 ```
 
-## JavaScript
-
-```javascript
-// File: app.js
+## Authentication
 
-// Import @heliyos/heliyos-api-core
-const { heliyos_app } = require("@heliyos/heliyos-api-core");
+Handles user authentication with support for Basic Auth, Bearer tokens, and API keys.
 
-// Get all routes
-const user_routes = require("./routes/v1/user/user_routes");
-
-const routes = [user_routes];
+```typescript
+import { authentication } from "@heliyos/heliyos-api-core";
 
-//
-// Configure options (optional)
-// If true, you must create a /static dir in root.
-// If you prefer no static directory, do not specify
-// a staticDir in options or set it to false.
-//
-const options = {
-  staticDir: true,
-};
+// Use as middleware
+app.use(authentication);
 
-// Start app
-const app = express();
-heliyos_app(app, routes, options);
+// Required environment variables:
+// SECRET_OF_SERVER
+// BASE_URL_AUTH_SERVER
+// SECRET_OF_AUTH_SERVER
 ```
 
-Importing specific modules:
+## Authorization
 
-```javascript
-const { validate } = require('@heliyos/heliyos-api-core');
+Role-based access control for resources.
 
-await validate(...);
+```typescript
+import { authorize_user } from "@heliyos/heliyos-api-core";
+
+const checkAccess = async (
+  organizationId: number,
+  userId: number,
+  action: string
+) => {
+  const { isAllowed, userRole } = await authorize_user(
+    organizationId,
+    userId,
+    action
+  );
+  return isAllowed;
+};
 ```
 
-## Run app
+## Axios HTTP Client
 
-Run `node ./app` or `node-ts ./src/app`
+Pre-configured Axios instances for internal services.
 
-## heliyos_app
-
-`heliyos_app` will provide server with external and internal middleware.
-
-### External middleware
+```typescript
+import { axios } from "@heliyos/heliyos-api-core";
 
-The following is applied:
+// Available instances:
+await axios.auth_server.get("/endpoint");
+await axios.billing_server.post("/endpoint", data);
+await axios.event_server.put("/endpoint", data);
+await axios.notification_server.delete("/endpoint");
+await axios.user_server.patch("/endpoint", data);
 
-```javascript
-app.use(helmet());
-app.use(cookie_parser());
-app.use(morgan("dev"));
-app.use(body_parser.json());
-app.use(body_parser.urlencoded({ extended: false }));
-app.use(express_validator());
-app.disable("x-powered-by");
+// Required environment variables for each server:
+// BASE_URL_AUTH_SERVER + SECRET_OF_AUTH_SERVER
+// BASE_URL_BILLING_SERVER + SECRET_OF_BILLING_SERVER
+// BASE_URL_EVENT_API_SERVER + SECRET_OF_EVENT_API_SERVER
+// BASE_URL_NOTIFICATION_SERVER + SECRET_OF_NOTIFICATION_SERVER
+// BASE_URL_USERS_SERVER + SECRET_OF_USERS_SERVER
 ```
 
-Set `options.skipExternals` to `true` to skip all externals.
+## Database (Knex)
 
-### Internal middleware
+Database connection and query builder with pagination support.
+
+```typescript
+import { knex } from "@heliyos/heliyos-api-core";
 
-The following is applied:
+// Regular queries
+const users = await knex("users").where({ active: true });
 
-```javascript
-app.use(force_https);
-app.use(apply_cors);
+// With pagination
+const results = await knex("users")
+  .where({ active: true })
+  .paginate(page, limit);
 
-app.use(<ROUTES>)
+// Results format:
+// {
+//   data: Array<T>,
+//   meta: {
+//     page: number,
+//     limit: number,
+//     offset: number,
+//     count: number
+//   }
+// }
 
-app.use(route_not_found);
-app.use(handle_errors);
+// Required environment variables:
+// DATABASE_URL
 ```
 
-Set `options.skipInternals` to `true` to skip internals other than ROUTES.
+## Validation
 
-### function signature
+Input validation using Joi.
 
-`heliyos_app(app, routes, options)` function has 3 parameters:
+```typescript
+import { validate, joiObject } from "@heliyos/heliyos-api-core";
 
-```javascript
-- app: Express      // required express app
-- routes: Router[]     // required express routes array
-- options?: IHeliyosAppOptions  // optional
+const schema = (joi) =>
+  joi.object({
+    name: joi.string().required(),
+    email: joi.string().email().required(),
+  });
 
-interface IHeliyosAppOptions {
- staticDir?: boolean;  // if true route /static for a "/static" directory
- skipExternals?: boolean; // if true external middleware will not be applied
- skipInternals?: boolean; // if true internal middleware will not be applied
-}
-```
+// Validate input
+validate(inputData, schema);
 
-# Modules
-
-This is a list of exported modules available.
-Be sure to read below to learn more and to set-up necessary
-environment variables for certain modules.
-
-```javascript
-export { authentication } from "./authentication";
-export { heliyos_app } from "./app";
-export { heliyos_axios as axios } from "./axios";
-export { heliyos_knex as knex } from "./knex";
-export { validate } from "./validate";
-export { auth_policy } from "./static/auth_policy_file";
-export { database_config } from "./knexfile";
-export { authorize_user } from "./authorization";
-export { send_email } from "./sendgrid_email_service";
-export { SQSUtil } from "./sqs";
+// Using joiObject directly
+const customSchema = joiObject.object({
+  // schema definition
+});
 ```
 
-## Knex: paginate method
-
-You can use `.paginate` as a chain method with knex:
+## Redis Client
 
-- `knex().paginate(page, limit)` function has 2 parameters.
+Redis connection management.
 
-### JavaScript
-
-```javascript
-const { knex } = require("@heliyos/heliyos-api-core");
-
-const logs = await knex("user.user_log")
-  .where({ store_id })
-  .orderBy("updated_at", "desc")
-  .paginate(+page, +limit);
+```typescript
+import { createRedisClient } from "@heliyos/heliyos-api-core";
 
-logs.data; // contains results
-logs.meta; // contains pagination meta: page, limit, offset, count
+const redisClient = createRedisClient({
+  url: "redis://localhost:6379",
+});
 ```
 
-### TypeScript
+## Pusher
 
-```javascript
+Real-time event broadcasting.
 
-import { knex } from '@heliyos/heliyos-api-core';
-
-const logs = await (
-    knex('user.user_log')
-        .where({ store_id })
-        .orderBy('updated_at', 'desc') as any
-)
-.paginate(+page, +limit);
+```typescript
+import { pusherTrigger, pusherTriggerBatch } from "@heliyos/heliyos-api-core";
 
-logs.data // contains results
-logs.meta // contains pagination meta: page, limit, offset, count
-```
+// Single event
+await pusherTrigger("channel-name", "event-name", { data: "payload" });
 
-## Validate
+// Batch events
+const batch = [
+  { channel: "channel1", name: "event1", data: {} },
+  { channel: "channel2", name: "event2", data: {} },
+];
+await pusherTriggerBatch(batch);
 
-You can use the `validate` module to validate using joi-validation library.
+// Required environment variables:
+// PUSHER_APP_ID
+// PUSHER_KEY
+// PUSHER_SECRET
+// PUSHER_CLUSTER
+```
 
-```javascript
-const schema_gen = (joi) => {
-  return joi.object({
-    property_id: joi.number().required(),
-    name: joi.string().required(),
-  });
-};
+## SQS (Message Queue)
 
-const input = {
-  property_id: container.input.property_id,
-  name: container.input.body.name,
-};
+AWS SQS integration for message queuing.
 
-validate(input, schema_gen);
-```
+```typescript
+import { SQSUtil } from "@heliyos/heliyos-api-core";
 
-## Authentication ENV Vars
+const sqs = new SQSUtil();
 
-You'll need to have the following env var for authentication module:
+// Write message
+await sqs.write(
+  {
+    resource: "users",
+    type: "INSERT",
+    objectId: { name: "user_id", value: "123" },
+    data: { name: "John" },
+  },
+  "queue-url",
+  "optional-group-id"
+);
 
-```javascript
-// Server
-process.env.SECRET_OF_SERVER;
+// Read message
+const messages = await sqs.read("queue-url");
 
-// Auth server
-process.env.BASE_URL_AUTH_SERVER;
-process.env.SECRET_OF_AUTH_SERVER;
+// Delete message
+await sqs.delete(receiptHandle, "queue-url");
 ```
 
-## SQS
+## Email Services
 
-Cartloop message queue service. This provides our means of sharing information between micro-services.
+Email sending with template support using Resend.
 
-### SQSUtil
+```typescript
+import { resendSendEmail } from "@heliyos/heliyos-api-core";
 
-```javascript
+await resendSendEmail(
+  ["recipient@example.com"],
+  "template-id",
+  { name: "John" },
+  "Email Subject"
+);
 
-import { SQSUtil } from '@heliyos/heliyos-api-core';
+// Required environment variables:
+// RESEND_API_KEY
+// RESEND_FROM_RECIPIENT
+```
 
-const sqs = new SQSUtil();
+## Environment Management
 
-// Write to sqs
-const queueURL = 'https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue';
-sqs.write({
-  resource: 'users',
-  type: 'INSERT',
-  objectId: { name: "user_uuid", value: "1234567890453" }
-  data: { name: "John", email: 'promise@cartloop.io' }
-}, queueURL);
+Load environment variables from AWS Secrets Manager.
 
-// Read from sqs
-sqs.read(queueURL);
+```typescript
+import { loadAppEnv } from "@heliyos/heliyos-api-core";
 
-// Delete from sqs
-// event is an import("aws-lambda").SQSEvent
-const eventRecord =  event.Records[0]
-const { receiptHandle } = eventRecord
-sqs.delete(receiptHandle, queueURL);
+const env = await loadAppEnv();
 
+// Required environment variables:
+// ENV_SECRET_NAME
 ```
 
-## Axios ENV vars
-
-You'll need to include env vars for the axios instances you plan to use.
-
-```javascript
-// Auth server
-process.env.BASE_URL_AUTH_SERVER;
-process.env.SECRET_OF_AUTH_SERVER;
+## Logging
 
-// Billing server
-process.env.BASE_URL_BILLING_SERVER;
-process.env.SECRET_OF_BILLING_SERVER;
+Structured logging with Winston.
 
-// Event server
-process.env.BASE_URL_EVENT_API_SERVER;
-process.env.SECRET_OF_EVENT_API_SERVER;
-
-// Notification server
-process.env.BASE_URL_NOTIFICATION_SERVER;
-process.env.SECRET_OF_NOTIFICATION_SERVER;
+```typescript
+import { logger } from "@heliyos/heliyos-api-core";
 
-// Users server
-process.env.BASE_URL_USERS_SERVER;
-process.env.SECRET_OF_USERS_SERVER;
+logger.info("Message", { meta: "data" });
+logger.error("Error occurred", { error });
+logger.warn("Warning message");
 ```
 
-## Development and Testing
+# Development
 
-To test the changes made locally in the package, with a local microservice, please follow the steps below:
+To test changes locally:
 
-1. Migrate to the `heliyos-api-core` project folder, make your code changes and run the following command in your terminal (root directory) to build the package. The below command will store
-   the built artifcats in the dist folder.
+1. Build the package:
 
-```
+```bash
 npm run build
 ```
 
-2. Pack the artifacts to use it in a project. This would create a compressed tar file. Run the following command in the repository's root directory
+2. Create a tarball:
 
-```
+```bash
 npm pack --pack-destination .
 ```
 
-3. Install the package in your microservice with the path to the tar file generated in the previoud step.
+3. Install in your project:
 
-```
-npm install  /Users/meowmeowuser/Siena/heliyos-api-core/heliyos-ai-heliyos-api-core-1.0.5.tgz
+```bash
+npm install /path/to/heliyos-api-core/heliyos-ai-heliyos-api-core-1.0.5.tgz
 ```
 
-4. Verify your package installation in the microservice app's `package.json`. It should show that the package has been installed from a file path `"@heliyos/heliyos-api-core": "file:../heliyos-api-core/heliyos-ai-heliyos-api-core-1.0.5.tgz"` under the dependencies.
+# Publishing
 
-5. Thats it! Test your package locally!
+To publish updates (admin only):
 
-## How to publish?
+1. Update version in package.json
 
-To publish a package to the npm org, you would need an npm token with publish rights (should be only done by the admin, once the PR is merged to staging).
-
-1. Update the version of the npm package in package.json and run the following to update the lock file
-
-```
-npm i
+```bash
+npm version patch|minor|major
 ```
 
 2. Build the project
 
-```
+```bash
 npm run build
 ```
 
-2. Login to npm (Only needed once!). Run the command in the terminal and follow the steps on the web to login
+3. Publish
 
-```
-npm login
-```
-
-3. Publish the built project
-
-```
+```bash
 npm publish
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heliyos/heliyos-api-core",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Heliyos's core api functions and middlewares. Its a private package hosted on npm.",
   "main": "./dist/index.js",
   "scripts": {