@pikku/core 0.6.9

package/dist/services/jwt-service.d.ts

@@ -0,0 +1,29 @@
+import { CoreUserSession } from '../types/core.types.js';
+/**
+ * Interface for handling JSON Web Tokens (JWT).
+ * @template UserSession - The type of the user session.
+ */
+export interface JWTService<UserSession = CoreUserSession> {
+    /**
+     * Encodes a payload into a JWT.
+     * @param expiresIn - The expiration time of the token.
+     * @param payload - The payload to encode.
+     * @returns A promise that resolves to the encoded JWT.
+     */
+    encode: <T extends any>(expiresIn: string, payload: T) => Promise<string>;
+    /**
+     * Decodes a JWT into its payload.
+     * @param hash - The JWT to decode.
+     * @param invalidHashError - An optional error to throw if the hash is invalid.
+     * @param debug - An optional flag for debugging.
+     * @returns A promise that resolves to the decoded payload.
+     */
+    decode: <T>(hash: string, invalidHashError?: Error, debug?: boolean) => Promise<T>;
+    /**
+     * Decodes a user session from a JWT.
+     * @param jwtToken - The JWT representing the user session.
+     * @param debug - An optional flag for debugging.
+     * @returns A promise that resolves to the decoded user session.
+     */
+    decodeSession: (jwtToken: string, debug?: any) => Promise<UserSession>;
+}

package/dist/services/jwt-service.js

@@ -0,0 +1 @@
+export {};

package/dist/services/local-content.d.ts

@@ -0,0 +1,33 @@
+import { ContentService } from './content-service.js';
+import { Logger } from './logger.js';
+export interface LocalContentConfig {
+    contentDirectory: string;
+    assetsUrl: string;
+    uploadUrl: string;
+}
+/**
+ * Service for handling local content operations.
+ */
+export declare abstract class LocalContent implements ContentService {
+    constructor(_config: LocalContentConfig, _logger: Logger);
+    abstract getUploadURL: (fileKey: string, contentType: string) => Promise<{
+        uploadUrl: string;
+        assetKey: string;
+    }>;
+    /**
+     * Initializes the local content service.
+     */
+    abstract init(): Promise<void>;
+    /**
+     * Signs a URL to provide secure access.
+     * @param url - The URL to sign.
+     * @returns A promise that resolves to the signed URL.
+     */
+    abstract signURL(url: string): Promise<string>;
+    /**
+     * Signs a content key to provide secure access to an asset.
+     * @param assetKey - The key of the asset to sign.
+     * @returns A promise that resolves to the signed content key URL.
+     */
+    abstract signContentKey(assetKey: string): Promise<string>;
+}

package/dist/services/local-content.js

@@ -0,0 +1,6 @@
+/**
+ * Service for handling local content operations.
+ */
+export class LocalContent {
+    constructor(_config, _logger) { }
+}

package/dist/services/local-secrets.d.ts

@@ -0,0 +1,26 @@
+import { SecretService } from './secret-service.js';
+import { VariablesService } from './variables-service.js';
+/**
+ * Service for retrieving secrets from environment variables.
+ */
+export declare class LocalSecretService implements SecretService {
+    private variablesService;
+    /**
+     * Creates an instance of LocalSecretService.
+     */
+    constructor(variablesService?: VariablesService);
+    /**
+     * Retrieves a secret by key.
+     * @param key - The key of the secret to retrieve.
+     * @returns A promise that resolves to the secret value.
+     * @throws {Error} If the secret is not found.
+     */
+    getSecretJSON<R>(key: string): Promise<R>;
+    /**
+     * Retrieves a secret by key.
+     * @param key - The key of the secret to retrieve.
+     * @returns A promise that resolves to the secret value.
+     * @throws {Error} If the secret is not found.
+     */
+    getSecret(key: string): Promise<string>;
+}

package/dist/services/local-secrets.js

@@ -0,0 +1,39 @@
+import { LocalVariablesService } from './local-variables.js';
+/**
+ * Service for retrieving secrets from environment variables.
+ */
+export class LocalSecretService {
+    variablesService;
+    /**
+     * Creates an instance of LocalSecretService.
+     */
+    constructor(variablesService = new LocalVariablesService()) {
+        this.variablesService = variablesService;
+    }
+    /**
+     * Retrieves a secret by key.
+     * @param key - The key of the secret to retrieve.
+     * @returns A promise that resolves to the secret value.
+     * @throws {Error} If the secret is not found.
+     */
+    async getSecretJSON(key) {
+        const value = await this.variablesService.get(key);
+        if (value) {
+            return JSON.parse(value);
+        }
+        throw new Error(`Secret Not Found: ${key}`);
+    }
+    /**
+     * Retrieves a secret by key.
+     * @param key - The key of the secret to retrieve.
+     * @returns A promise that resolves to the secret value.
+     * @throws {Error} If the secret is not found.
+     */
+    async getSecret(key) {
+        const value = await this.variablesService.get(key);
+        if (value) {
+            return value;
+        }
+        throw new Error(`Secret Not Found: ${key}`);
+    }
+}

package/dist/services/local-variables.d.ts

@@ -0,0 +1,7 @@
+import { VariablesService } from './variables-service.js';
+export declare class LocalVariablesService implements VariablesService {
+    private variables;
+    constructor(variables?: Record<string, string | undefined>);
+    getAll(): Promise<Record<string, string | undefined>> | Record<string, string | undefined>;
+    get(name: string): Promise<string | undefined> | string | undefined;
+}

package/dist/services/local-variables.js

@@ -0,0 +1,12 @@
+export class LocalVariablesService {
+    variables;
+    constructor(variables = process.env) {
+        this.variables = variables;
+    }
+    getAll() {
+        return this.variables || {};
+    }
+    get(name) {
+        return this.variables[name];
+    }
+}

package/dist/services/logger-console.d.ts

@@ -0,0 +1,52 @@
+import { Logger, LogLevel } from './logger.js';
+/**
+ * A logger implementation that logs messages to the console.
+ */
+export declare class ConsoleLogger implements Logger {
+    /**
+     * The current logging level.
+     */
+    private level;
+    /**
+     * Sets the logging level.
+     * @param level - The logging level to set.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Logs a trace message.
+     * @param message - The message to log.
+     * @param meta - Additional metadata to log.
+     */
+    trace?(message: string, ...meta: any[]): void;
+    /**
+     * Logs a debug message.
+     * @param message - The message to log.
+     * @param meta - Additional metadata to log.
+     */
+    debug(message: string, ...meta: any[]): void;
+    /**
+     * Logs an informational message.
+     * @param messageOrObj - The message or object to log.
+     * @param meta - Additional metadata to log.
+     */
+    info(messageOrObj: string | Record<string, any>, ...meta: any[]): void;
+    /**
+     * Logs a warning message.
+     * @param messageOrObj - The message or object to log.
+     * @param meta - Additional metadata to log.
+     */
+    warn(messageOrObj: string | Record<string, any>, ...meta: any[]): void;
+    /**
+     * Logs an error message.
+     * @param messageOrObj - The message, object, or error to log.
+     * @param meta - Additional metadata to log.
+     */
+    error(messageOrObj: string | Record<string, any> | Error, ...meta: any[]): void;
+    /**
+     * Logs a message at a specified level.
+     * @param level - The logging level.
+     * @param message - The message to log.
+     * @param meta - Additional metadata to log.
+     */
+    log(level: string, message: string, ...meta: any[]): void;
+}

package/dist/services/logger-console.js

@@ -0,0 +1,82 @@
+import { LogLevel } from './logger.js';
+/**
+ * A logger implementation that logs messages to the console.
+ */
+export class ConsoleLogger {
+    /**
+     * The current logging level.
+     */
+    level = LogLevel.info;
+    /**
+     * Sets the logging level.
+     * @param level - The logging level to set.
+     */
+    setLevel(level) {
+        this.level = level;
+    }
+    /**
+     * Logs a trace message.
+     * @param message - The message to log.
+     * @param meta - Additional metadata to log.
+     */
+    trace(message, ...meta) {
+        if (this.level <= LogLevel.trace) {
+            console.trace('TRACE:', message, ...meta);
+        }
+    }
+    /**
+     * Logs a debug message.
+     * @param message - The message to log.
+     * @param meta - Additional metadata to log.
+     */
+    debug(message, ...meta) {
+        if (this.level <= LogLevel.debug) {
+            console.debug('DEBUG:', message, ...meta);
+        }
+    }
+    /**
+     * Logs an informational message.
+     * @param messageOrObj - The message or object to log.
+     * @param meta - Additional metadata to log.
+     */
+    info(messageOrObj, ...meta) {
+        if (this.level <= LogLevel.info) {
+            console.info('INFO:', messageOrObj, ...meta);
+        }
+    }
+    /**
+     * Logs a warning message.
+     * @param messageOrObj - The message or object to log.
+     * @param meta - Additional metadata to log.
+     */
+    warn(messageOrObj, ...meta) {
+        if (this.level <= LogLevel.warn) {
+            console.warn('WARN:', messageOrObj, ...meta);
+        }
+    }
+    /**
+     * Logs an error message.
+     * @param messageOrObj - The message, object, or error to log.
+     * @param meta - Additional metadata to log.
+     */
+    error(messageOrObj, ...meta) {
+        if (this.level <= LogLevel.error) {
+            console.error('ERROR:', messageOrObj instanceof Error ? messageOrObj.message : messageOrObj, ...meta);
+            if (messageOrObj instanceof Error) {
+                console.error('STACK:', messageOrObj.stack);
+            }
+        }
+    }
+    /**
+     * Logs a message at a specified level.
+     * @param level - The logging level.
+     * @param message - The message to log.
+     * @param meta - Additional metadata to log.
+     */
+    log(level, message, ...meta) {
+        const logLevel = LogLevel[level];
+        if (this.level <= logLevel) {
+            console.log(`${level.toUpperCase()}:`, message, ...meta);
+        }
+    }
+}

package/dist/services/logger.d.ts

@@ -0,0 +1,48 @@
+export declare enum LogLevel {
+    'trace' = 0,// Add this level
+    'debug' = 1,
+    'info' = 2,
+    'warn' = 3,
+    'error' = 4,
+    'critical' = 5
+}
+/**
+ * Interface for logging messages at various levels.
+ */
+export interface Logger {
+    /**
+     * Logs an informational message.
+     * @param messageOrObj - The message or object to log.
+     * @param meta - Additional metadata to log.
+     */
+    info(messageOrObj: string | Record<string, any>, ...meta: any[]): void;
+    /**
+     * Logs a warning message.
+     * @param messageOrObj - The message or object to log.
+     * @param meta - Additional metadata to log.
+     */
+    warn(messageOrObj: string | Record<string, any>, ...meta: any[]): void;
+    /**
+     * Logs an error message.
+     * @param messageOrObj - The message, object, or error to log.
+     * @param meta - Additional metadata to log.
+     */
+    error(messageOrObj: string | Record<string, any> | Error, ...meta: any[]): void;
+    /**
+     * Logs a debug message.
+     * @param message - The message to log.
+     * @param meta - Additional metadata to log.
+     */
+    debug(message: string, ...meta: any[]): void;
+    /**
+     * Logs a trace message.
+     * @param message - The message to log.
+     * @param meta - Additional metadata to log.
+     */
+    trace?(message: string, ...meta: any[]): void;
+    /**
+     * Sets the logging level.
+     * @param level - The logging level to set.
+     */
+    setLevel(level: LogLevel): void;
+}

package/dist/services/logger.js

@@ -0,0 +1,9 @@
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["trace"] = 0] = "trace";
+    LogLevel[LogLevel["debug"] = 1] = "debug";
+    LogLevel[LogLevel["info"] = 2] = "info";
+    LogLevel[LogLevel["warn"] = 3] = "warn";
+    LogLevel[LogLevel["error"] = 4] = "error";
+    LogLevel[LogLevel["critical"] = 5] = "critical";
+})(LogLevel || (LogLevel = {}));

package/dist/services/schema-service.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Interface for a schema service that handles schema compilation, validation, and management.
+ */
+export interface SchemaService {
+    /**
+     * Compiles a schema with the provided name and value, making it available for use.
+     * @param {string} name - The unique name for the schema.
+     * @param {any} value - The schema definition or configuration to be compiled.
+     * @returns {Promise<void> | void} A promise if asynchronous, or void if synchronous.
+     */
+    compileSchema: (name: string, value: any) => Promise<void> | void;
+    /**
+     * Validates data against a specified schema.
+     * @param {string} schema - The name of the schema to validate against.
+     * @param {any} data - The data to validate against the schema.
+     * @returns {Promise<void> | void} A promise if asynchronous, or void if synchronous.
+     */
+    validateSchema: (schema: string, data: any) => Promise<void> | void;
+    /**
+     * Retrieves a set of all registered schema names.
+     * @returns {Set<string>} A set containing the names of all available schemas.
+     */
+    getSchemaNames: () => Set<string>;
+}

package/dist/services/schema-service.js

@@ -0,0 +1 @@
+export {};

package/dist/services/secret-service.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface for retrieving secrets.
+ */
+export interface SecretService {
+    /**
+     * Retrieves a secret by key.
+     * @param key - The key of the secret to retrieve.
+     * @returns A promise that resolves to the secret value.
+     */
+    getSecretJSON<Return = {}>(key: string): Promise<Return>;
+    /**
+     * Retrieves a secret by key.
+     * @param key - The key of the secret to retrieve.
+     * @returns A promise that resolves to the secret value.
+     */
+    getSecret(key: string): Promise<string>;
+}

package/dist/services/secret-service.js

@@ -0,0 +1 @@
+export {};

package/dist/services/user-session-service.d.ts

@@ -0,0 +1,6 @@
+import { CoreUserSession } from '../types/core.types.js';
+export interface UserSessionService<UserSession extends CoreUserSession> {
+    setSession: (session: UserSession) => Promise<void> | void;
+    deleteSession: () => Promise<void> | void;
+    getSession: () => Promise<UserSession | void> | UserSession | void;
+}

package/dist/services/user-session-service.js

@@ -0,0 +1 @@
+export {};

package/dist/services/variables-service.d.ts

@@ -0,0 +1,4 @@
+export interface VariablesService {
+    get: (name: string) => Promise<string | undefined> | string | undefined;
+    getAll: () => Promise<Record<string, string | undefined>> | Record<string, string | undefined>;
+}

package/dist/services/variables-service.js

@@ -0,0 +1 @@
+export {};

package/dist/types/core.types.d.ts

@@ -0,0 +1,109 @@
+import type { Logger, LogLevel } from '../services/logger.js';
+import type { HTTPSessionService } from '../http/http-session-service.js';
+import { VariablesService } from '../services/variables-service.js';
+import { EventHubService } from '../channel/eventhub-service.js';
+import { SchemaService } from '../services/schema-service.js';
+import { enforceChannelAccess } from '../channel/channel.types.js';
+import { enforceHTTPAccess, PikkuHTTP } from '../http/http-routes.types.js';
+import { UserSessionService } from '../services/user-session-service.js';
+import { JWTService } from '../services/jwt-service.js';
+import { SecretService } from '../services/secret-service.js';
+export type MakeRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+/**
+ * Represents a JSON primitive type which can be a string, number, boolean, null, or undefined.
+ */
+export type JSONPrimitive = string | number | boolean | null | undefined;
+/**
+ * Represents a JSON value which can be a primitive, an array, or an object.
+ */
+export type JSONValue = JSONPrimitive | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+/**
+ * Utility type for making certain keys required and leaving the rest as optional.
+ */
+export type PickRequired<T, K extends keyof T> = Required<Pick<T, K>> & Partial<T>;
+/**
+ * Utility type for making certain keys optional while keeping the rest required.
+ */
+export type PickOptional<T, K extends keyof T> = Partial<T> & Pick<T, K>;
+/**
+ * Utility type that ensures at least one key in the given type `T` is required.
+ */
+export type RequireAtLeastOne<T> = {
+    [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>;
+}[keyof T];
+/**
+ * Interface for the core configuration settings of Pikku.
+ */
+export type CoreConfig<Config extends Record<string, unknown> = {}> = {
+    /** The log level for the application. */
+    logLevel?: LogLevel;
+    /** The maximum compute time allowed, in milliseconds (optional). */
+    maximumComputeTime?: number;
+    /** Secrets used by the application (optional). */
+    secrets?: {};
+} & Config;
+/**
+ * Represents a core user session, which can be extended for more specific session information.
+ */
+export type CoreUserSession<UserSession = unknown> = UserSession;
+/**
+ * Interface for core singleton services provided by Pikku.
+ */
+export type CoreSingletonServices<Config extends CoreConfig = CoreConfig, UserSession extends CoreUserSession = CoreUserSession, UserServices extends Record<string, unknown> = {}> = {
+    /** The http permission service used for authorization (optional). */
+    enforceHTTPAccess?: enforceHTTPAccess;
+    /** The channel permission service used by the application (optional). */
+    enforceChannelAccess?: enforceChannelAccess;
+    /** JWT Service */
+    jwt?: JWTService<UserSession>;
+    /** The session service used by the application (optional). */
+    httpSessionService?: HTTPSessionService;
+    /** The schema library used to validate data */
+    schemaService?: SchemaService;
+    /** The core configuration for the application. */
+    config: Config;
+    /** The logger used by the application. */
+    logger: Logger;
+    /** The variable service to be used */
+    variablesService: VariablesService;
+    /** The subscription service that is passed to streams */
+    eventHub?: EventHubService<unknown>;
+    /** SecretServce  */
+    secretService?: SecretService;
+} & UserServices;
+/**
+ * Represents different forms of interaction within Pikku and the outside world.
+ */
+export interface PikkuInteractions {
+    http?: PikkuHTTP;
+}
+/**
+ * Represents the core services used by Pikku, including singleton services and the request/response interaction.
+ */
+export type CoreServices<SingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession, CoreServices extends Record<string, unknown> = {}> = SingletonServices & PikkuInteractions & {
+    userSession?: UserSessionService<UserSession>;
+} & CoreServices;
+export type SessionServices<SingletonServices extends CoreSingletonServices = CoreSingletonServices, Services = CoreServices<SingletonServices>> = Omit<Services, keyof SingletonServices | keyof PikkuInteractions | 'session'>;
+/**
+ * Defines a function type for creating singleton services from the given configuration.
+ */
+export type CreateSingletonServices<Config extends CoreConfig, SingletonServices extends CoreSingletonServices> = (config: Config, existingServices?: Partial<SingletonServices>) => Promise<SingletonServices>;
+/**
+ * Defines a function type for creating session-specific services.
+ */
+export type CreateSessionServices<SingletonServices extends CoreSingletonServices = CoreSingletonServices, Services extends CoreServices<SingletonServices> = CoreServices<SingletonServices>, UserSession extends CoreUserSession = CoreUserSession> = (services: SingletonServices, interaction: PikkuInteractions, session: UserSession | undefined) => Promise<SessionServices<Services, SingletonServices>>;
+/**
+ * Defines a function type for creating config.
+ */
+export type CreateConfig<Config extends CoreConfig> = (variablesService?: VariablesService) => Promise<Config>;
+/**
+ * Represents the documentation for a route, including summary, description, tags, and errors.
+ */
+export type APIDocs = {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    errors?: string[];
+};

package/dist/types/core.types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/functions.types.d.ts

@@ -0,0 +1,27 @@
+import type { CoreServices, CoreUserSession } from './core.types.js';
+/**
+ * Represents a core API function that performs an operation using core services and a user session.
+ *
+ * @template In - The input type.
+ * @template Out - The output type.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Session - The session type, defaults to `CoreUserSession`.
+ */
+export type CoreAPIFunction<In, Out, Services = CoreServices, Session = CoreUserSession> = (services: Services, data: In, session: Session) => Promise<Out>;
+/**
+ * Represents a core API function that can be used without a session.
+ *
+ * @template In - The input type.
+ * @template Out - The output type.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Session - The session type, defaults to `CoreUserSession`.
+ */
+export type CoreAPIFunctionSessionless<In, Out, Services = CoreServices, Session = CoreUserSession> = (services: Services, data: In, session?: Session) => Promise<Out>;
+/**
+ * Represents a function that checks permissions for a given API operation.
+ *
+ * @template In - The input type.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Session - The session type, defaults to `CoreUserSession`.
+ */
+export type CoreAPIPermission<In = any, Services = CoreServices, Session = CoreUserSession> = (services: Services, data: In, session?: Session) => Promise<boolean>;

package/dist/types/functions.types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+import { Logger } from './services/logger.js';
+export declare const closeSessionServices: (logger: Logger, sessionServices: Record<string, any>) => Promise<void>;

package/dist/utils.js

@@ -0,0 +1,15 @@
+// TODO: SessionServices probably needs it's own type
+// but is an issue for the future and will be tackled
+// with dependency injection
+export const closeSessionServices = async (logger, sessionServices) => {
+    await Promise.all(Object.values(sessionServices).map(async (service) => {
+        if (service?.close) {
+            try {
+                await service.close();
+            }
+            catch (e) {
+                logger.error(e);
+            }
+        }
+    }));
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@pikku/core",
+  "version": "0.6.9",
+  "author": "yasser.fadl@gmail.com",
+  "license": "MIT",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "tsc": "tsc",
+    "build:esm": "tsc -b",
+    "build": "yarn build:esm",
+    "ncu": "ncu",
+    "release": "npm run build && npm test",
+    "test": "bash run-tests.sh",
+    "test:watch": "bash run-tests.sh --watch",
+    "test:coverage": "bash run-tests.sh --coverage"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./channel": "./dist/channel/index.js",
+    "./channel/local": "./dist/channel/local/index.js",
+    "./channel/serverless": "./dist/channel/serverless/index.js",
+    "./http": "./dist/http/index.js",
+    "./http/pikku-http-session-service": "./dist/http/pikku-http-session-service.js",
+    "./http/pikku-http-abstract-response": "./dist/http/pikku-http-abstract-response.js",
+    "./http/pikku-http-abstract-request": "./dist/http/pikku-http-abstract-request.js",
+    "./errors": "./dist/errors/index.js",
+    "./scheduler": "./dist/scheduler/index.js",
+    "./services": "./dist/services/index.js",
+    "./schema": "./dist/schema.js",
+    "./types": "./dist/types/index.d.ts"
+  },
+  "dependencies": {
+    "@types/cookie": "^0.6.0",
+    "@types/uuid": "^10.0.0",
+    "cookie": "^1.0.1",
+    "path-to-regexp": "^8.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.8",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}