@pikku/core 0.6.9

package/dist/http/pikku-http-session-service.d.ts

@@ -0,0 +1,45 @@
+import { HTTPSessionService } from './http-session-service.js';
+import { JWTService } from '../services/jwt-service.js';
+import { PikkuHTTPAbstractRequest } from './pikku-http-abstract-request.js';
+import { PikkuQuery } from './http-routes.types.js';
+/**
+ * The `PikkuHTTPSessionService` class provides session management capabilities, including handling JWT-based sessions,
+ * cookie-based sessions, and API key-based sessions. It allows for retrieving and transforming user sessions based on different
+ * authentication mechanisms.
+ *
+ * @template UserSession - The type representing a user session.
+ */
+export declare class PikkuHTTPSessionService<UserSession> implements HTTPSessionService<UserSession> {
+    private jwtService;
+    private options;
+    /**
+     * Constructs a new instance of the `PikkuHTTPSessionService` class.
+     *
+     * @param jwtService - The service for handling JWT operations.
+     * @param options - Options for configuring the session service.
+     */
+    constructor(jwtService: JWTService<UserSession>, options: {
+        cookieNames?: string[];
+        getSessionForCookieValue?: (cookieValue: string, cookieName: string) => Promise<UserSession>;
+        getSessionForQueryValue?: (queryValue: PikkuQuery) => Promise<UserSession> | undefined;
+        getSessionForAPIKey?: (apiKey: string) => Promise<UserSession> | undefined;
+        transformSession?: (session: any) => Promise<UserSession>;
+    });
+    /**
+     * Retrieves a session from cookies if available.
+     *
+     * @param request - The request object containing cookies.
+     * @returns A promise that resolves to the user session, or `undefined` if no session is found.
+     */
+    private getCookieSession;
+    /**
+     * Retrieves the user session based on available credentials (JWT, API key, or cookies).
+     *
+     * @param credentialsRequired - Whether credentials are required to proceed.
+     * @param request - The request object containing headers and cookies.
+     * @param debugJWTDecode - Whether to enable debugging for JWT decoding.
+     * @returns A promise that resolves to the user session, or `undefined` if no session is found and credentials are not required.
+     * @throws {MissingSessionError} - Throws an error if credentials are required but no session is found.
+     */
+    getUserSession(credentialsRequired: boolean, request: PikkuHTTPAbstractRequest, debugJWTDecode?: boolean): Promise<UserSession | undefined>;
+}

package/dist/http/pikku-http-session-service.js

@@ -0,0 +1,92 @@
+import { InvalidSessionError, MissingSessionError } from '../errors/errors.js';
+/**
+ * The `PikkuHTTPSessionService` class provides session management capabilities, including handling JWT-based sessions,
+ * cookie-based sessions, and API key-based sessions. It allows for retrieving and transforming user sessions based on different
+ * authentication mechanisms.
+ *
+ * @template UserSession - The type representing a user session.
+ */
+export class PikkuHTTPSessionService {
+    jwtService;
+    options;
+    /**
+     * Constructs a new instance of the `PikkuHTTPSessionService` class.
+     *
+     * @param jwtService - The service for handling JWT operations.
+     * @param options - Options for configuring the session service.
+     */
+    constructor(jwtService, options) {
+        this.jwtService = jwtService;
+        this.options = options;
+    }
+    /**
+     * Retrieves a session from cookies if available.
+     *
+     * @param request - The request object containing cookies.
+     * @returns A promise that resolves to the user session, or `undefined` if no session is found.
+     */
+    async getCookieSession(request) {
+        const cookies = request.getCookies();
+        if (!cookies) {
+            return;
+        }
+        let cookieName;
+        if (this.options.cookieNames) {
+            for (const name of this.options.cookieNames) {
+                if (cookies[name]) {
+                    cookieName = name;
+                }
+            }
+        }
+        if (!cookieName) {
+            return;
+        }
+        const cookieValue = cookies[cookieName];
+        if (!cookieValue) {
+            return;
+        }
+        if (!this.options.getSessionForCookieValue) {
+            return;
+        }
+        return await this.options.getSessionForCookieValue(cookieValue, cookieName);
+    }
+    /**
+     * Retrieves the user session based on available credentials (JWT, API key, or cookies).
+     *
+     * @param credentialsRequired - Whether credentials are required to proceed.
+     * @param request - The request object containing headers and cookies.
+     * @param debugJWTDecode - Whether to enable debugging for JWT decoding.
+     * @returns A promise that resolves to the user session, or `undefined` if no session is found and credentials are not required.
+     * @throws {MissingSessionError} - Throws an error if credentials are required but no session is found.
+     */
+    async getUserSession(credentialsRequired, request, debugJWTDecode) {
+        let userSession;
+        const authorization = request.getHeader('authorization') || request.getHeader('Authorization');
+        if (authorization) {
+            const [part1, part2] = authorization.split(' ');
+            if (part1 !== 'Bearer' || !part2) {
+                throw new InvalidSessionError();
+            }
+            userSession = await this.jwtService.decode(part2, undefined, debugJWTDecode);
+        }
+        if (!userSession && this.options.getSessionForAPIKey) {
+            const apiKey = request.getHeader('x-api-key');
+            if (apiKey) {
+                userSession = await this.options.getSessionForAPIKey(apiKey);
+            }
+        }
+        if (!userSession && this.options.getSessionForCookieValue) {
+            userSession = await this.getCookieSession(request);
+        }
+        if (!userSession && this.options.getSessionForQueryValue) {
+            userSession = await this.options.getSessionForQueryValue(request.getQuery());
+        }
+        if (!userSession && credentialsRequired) {
+            throw new MissingSessionError();
+        }
+        if (userSession && this.options.transformSession) {
+            return await this.options.transformSession(userSession);
+        }
+        return userSession;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @module @pikku/core
+ */
+export * from './types/core.types.js';
+export * from './types/functions.types.js';
+export * from './pikku-request.js';
+export * from './pikku-response.js';
+export * from './services/index.js';
+export * from './http/index.js';
+export * from './channel/index.js';
+export * from './scheduler/index.js';
+export { addRoute } from './http/http-route-runner.js';
+export { addChannel } from './channel/channel-runner.js';
+export { addScheduledTask } from './scheduler/scheduler-runner.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @module @pikku/core
+ */
+export * from './types/core.types.js';
+export * from './types/functions.types.js';
+export * from './pikku-request.js';
+export * from './pikku-response.js';
+export * from './services/index.js';
+export * from './http/index.js';
+export * from './channel/index.js';
+export * from './scheduler/index.js';
+export { addRoute } from './http/http-route-runner.js';
+export { addChannel } from './channel/channel-runner.js';
+export { addScheduledTask } from './scheduler/scheduler-runner.js';

package/dist/permissions.d.ts

@@ -0,0 +1,10 @@
+import { CoreServices, CoreUserSession } from './types/core.types.js';
+import { CoreAPIPermission } from './types/functions.types.js';
+/**
+ * This function validates permissions by iterating over permission groups and executing the corresponding permission functions. If all functions in at least one group return true, the permission is considered valid.
+ * @param services - The core services required for permission validation.
+ * @param data - The data to be used in the permission validation functions.
+ * @param session - An optional user session for permission validation.
+ * @returns A promise that resolves to void.
+ */
+export declare const verifyPermissions: (permissions: Record<string, CoreAPIPermission<any>[] | CoreAPIPermission<any>> | undefined, services: CoreServices, data: any, session?: CoreUserSession) => Promise<boolean>;

package/dist/permissions.js

@@ -0,0 +1,32 @@
+/**
+ * This function validates permissions by iterating over permission groups and executing the corresponding permission functions. If all functions in at least one group return true, the permission is considered valid.
+ * @param services - The core services required for permission validation.
+ * @param data - The data to be used in the permission validation functions.
+ * @param session - An optional user session for permission validation.
+ * @returns A promise that resolves to void.
+ */
+export const verifyPermissions = async (permissions, services, data, session) => {
+    if (!permissions) {
+        return true;
+    }
+    let valid = false;
+    const permissionGroups = Object.values(permissions);
+    if (permissionGroups.length === 0) {
+        return true;
+    }
+    for (const funcs of permissionGroups) {
+        if (funcs instanceof Array) {
+            const permissioned = await Promise.all(funcs.map((func) => func(services, data, session)));
+            if (permissioned.every((result) => result)) {
+                valid = true;
+            }
+        }
+        else {
+            valid = await funcs(services, data, session);
+        }
+        if (valid) {
+            return true;
+        }
+    }
+    return false;
+};

package/dist/pikku-request.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Simplest class to represent a pikku request.
+ * @template In - The type of the request body.
+ * @group RequestResponse
+ */
+export declare abstract class PikkuRequest<In = any> {
+    private data?;
+    constructor(data?: In | undefined);
+    /**
+     * Retrieves the data
+     * @returns A promise that resolves to an object containing the combined data.
+     */
+    getData(): Promise<In>;
+}

package/dist/pikku-request.js

@@ -0,0 +1,21 @@
+/**
+ * Simplest class to represent a pikku request.
+ * @template In - The type of the request body.
+ * @group RequestResponse
+ */
+export class PikkuRequest {
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+    /**
+     * Retrieves the data
+     * @returns A promise that resolves to an object containing the combined data.
+     */
+    async getData() {
+        if (!this.data) {
+            throw new Error('Data not found');
+        }
+        return this.data;
+    }
+}

package/dist/pikku-response.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Abstract class representing a pikku response.
+ * @group RequestResponse
+ */
+export declare abstract class PikkuResponse {
+}

package/dist/pikku-response.js

@@ -0,0 +1,6 @@
+/**
+ * Abstract class representing a pikku response.
+ * @group RequestResponse
+ */
+export class PikkuResponse {
+}

package/dist/scheduler/index.d.ts

@@ -0,0 +1,3 @@
+export * from './scheduler.types.js';
+export { runScheduledTask, getScheduledTasks, addScheduledTask, clearScheduledTasks, setScheduledTasksMeta, } from './scheduler-runner.js';
+export * from './log-schedulers.js';

package/dist/scheduler/index.js

@@ -0,0 +1,3 @@
+export * from './scheduler.types.js';
+export { runScheduledTask, getScheduledTasks, addScheduledTask, clearScheduledTasks, setScheduledTasksMeta, } from './scheduler-runner.js';
+export * from './log-schedulers.js';

package/dist/scheduler/log-schedulers.d.ts

@@ -0,0 +1,6 @@
+import { Logger } from '../services/index.js';
+/**
+ * Logs all the loaded scheduled tasks.
+ * @param logger - A logger for logging information.
+ */
+export declare const logSchedulers: (logger: Logger) => void;

package/dist/scheduler/log-schedulers.js

@@ -0,0 +1,17 @@
+import { getScheduledTasks } from './scheduler-runner.js';
+/**
+ * Logs all the loaded scheduled tasks.
+ * @param logger - A logger for logging information.
+ */
+export const logSchedulers = (logger) => {
+    const { scheduledTasks } = getScheduledTasks();
+    if (scheduledTasks.size === 0) {
+        logger.info('No scheduled tasks added');
+        return;
+    }
+    let scheduledTasksMessage = 'Scheduled tasks:';
+    scheduledTasks.forEach(({ schedule }, name) => {
+        scheduledTasksMessage += `\n\t- ${name} -> ${schedule}`;
+    });
+    logger.info(scheduledTasksMessage);
+};

package/dist/scheduler/scheduler-runner.d.ts

@@ -0,0 +1,21 @@
+import type { CoreServices, CoreSingletonServices, CoreUserSession, CreateSessionServices } from '../types/core.types.js';
+import type { CoreScheduledTask, ScheduledTasksMeta } from './scheduler.types.js';
+import type { CoreAPIFunctionSessionless } from '../types/functions.types.js';
+export type RunScheduledTasksParams = {
+    name: string;
+    session?: CoreUserSession;
+    singletonServices: CoreSingletonServices;
+    createSessionServices?: CreateSessionServices<CoreSingletonServices, CoreServices<CoreSingletonServices>, CoreUserSession>;
+};
+export declare const addScheduledTask: <APIFunction extends CoreAPIFunctionSessionless<void, void>>(scheduledTask: CoreScheduledTask<APIFunction>) => void;
+export declare const clearScheduledTasks: () => void;
+export declare const setScheduledTasksMeta: (_scheduledTasksMeta: ScheduledTasksMeta) => void;
+/**
+ * Returns all the cron jobs
+ * @internal
+ */
+export declare const getScheduledTasks: () => {
+    scheduledTasks: Map<string, CoreScheduledTask>;
+    scheduledTasksMeta: any;
+};
+export declare function runScheduledTask<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession, Services extends CoreServices<SingletonServices> = CoreServices<SingletonServices>>({ name, session, singletonServices, createSessionServices, }: RunScheduledTasksParams): Promise<void>;

package/dist/scheduler/scheduler-runner.js

@@ -0,0 +1,73 @@
+import { getErrorResponse } from '../errors/error-handler.js';
+import { closeSessionServices } from '../utils.js';
+if (!global.pikku?.scheduledTasks) {
+    global.pikku = global.pikku || {};
+    global.pikku.scheduledTasks = new Map();
+    global.pikku.scheduledTasksMeta = [];
+}
+const scheduledTasks = () => {
+    return global.pikku.scheduledTasks;
+};
+const scheduledTasksMeta = (data) => {
+    if (data) {
+        global.pikku.scheduledTasksMeta = data;
+    }
+    return global.pikku.scheduledTasksMeta;
+};
+export const addScheduledTask = (scheduledTask) => {
+    if (scheduledTasks().has(scheduledTask.name)) {
+        throw new Error(`Scheduled task already exists: ${scheduledTask.name}`);
+    }
+    scheduledTasks().set(scheduledTask.name, scheduledTask);
+};
+export const clearScheduledTasks = () => {
+    scheduledTasks().clear();
+};
+export const setScheduledTasksMeta = (_scheduledTasksMeta) => {
+    scheduledTasksMeta(_scheduledTasksMeta);
+};
+/**
+ * Returns all the cron jobs
+ * @internal
+ */
+export const getScheduledTasks = () => {
+    return {
+        scheduledTasks: scheduledTasks(),
+        scheduledTasksMeta: scheduledTasksMeta(),
+    };
+};
+class ScheduledTaskNotFoundError extends Error {
+    constructor(title) {
+        super(`Scheduled task not found: ${title}`);
+    }
+}
+export async function runScheduledTask({ name, session, singletonServices, createSessionServices, }) {
+    let sessionServices;
+    const trackerId = crypto.randomUUID().toString();
+    try {
+        const task = scheduledTasks().get(name);
+        if (!task) {
+            throw new ScheduledTaskNotFoundError(`Scheduled task not found: ${name}`);
+        }
+        singletonServices.logger.info(`Running schedule task: ${name} | schedule: ${task.schedule}}`);
+        let allServices = singletonServices;
+        if (createSessionServices) {
+            const sessionServices = await createSessionServices(singletonServices, {}, session);
+            allServices = { ...singletonServices, ...sessionServices };
+        }
+        await task.func(allServices, undefined, session);
+    }
+    catch (e) {
+        const errorResponse = getErrorResponse(e);
+        if (errorResponse != null) {
+            singletonServices.logger.warn(`Error id: ${trackerId}`);
+            singletonServices.logger.error(e);
+        }
+        throw e;
+    }
+    finally {
+        if (sessionServices) {
+            await closeSessionServices(singletonServices.logger, sessionServices);
+        }
+    }
+}

package/dist/scheduler/scheduler.types.d.ts

@@ -0,0 +1,21 @@
+import { APIDocs, CoreUserSession } from '../types/core.types.js';
+import { CoreAPIFunctionSessionless } from '../types/functions.types.js';
+/**
+ * Represents metadata for scheduled tasks, including title, schedule, and documentation.
+ */
+export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> = Array<{
+    name: string;
+    schedule: string;
+    session?: UserSession;
+    docs?: APIDocs;
+}>;
+/**
+ * Represents a core scheduled task.
+ */
+export type CoreScheduledTask<APIFunction = CoreAPIFunctionSessionless<void, void>, UserSession extends CoreUserSession = CoreUserSession> = {
+    name: string;
+    schedule: string;
+    func: APIFunction;
+    docs?: APIDocs;
+    session?: UserSession;
+};

package/dist/scheduler/scheduler.types.js

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

package/dist/schema.d.ts

@@ -0,0 +1,26 @@
+import { Logger } from './services/logger.js';
+import { SchemaService } from './services/schema-service.js';
+/**
+ * Retrieves the global schemas map.
+ * @returns A map of schemas.
+ */
+export declare const getSchemas: () => any;
+/**
+ * Retrieves a schema from the schemas map.
+ * @returns A schema.
+ */
+export declare const getSchema: (schemaName: string) => any;
+/**
+ * Adds a schema to the global schemas map.
+ * @param name - The name of the schema.
+ * @param value - The schema value.
+ * @ignore
+ */
+export declare const addSchema: (name: string, value: any) => void;
+/**
+ * Loads a schema and compiles it into a validator.
+ * @param logger - A logger for logging information.
+ */
+export declare const compileAllSchemas: (logger: Logger, schemaService?: SchemaService) => void;
+export declare const coerceQueryStringToArray: (schemaName: string, data: any) => void;
+export declare const validateAndCoerce: (logger: Logger, schemaService: SchemaService | undefined, schemaName: string | undefined | null, data: any, coerceToArray: boolean) => void;

package/dist/schema.js

@@ -0,0 +1,100 @@
+import { getRoutes } from './http/http-route-runner.js';
+import { BadRequestError } from './errors/errors.js';
+/**
+ * Retrieves the global schemas map.
+ * @returns A map of schemas.
+ */
+export const getSchemas = () => {
+    if (!global.pikkuSchemas) {
+        global.pikkuSchemas = new Map();
+    }
+    return global.pikkuSchemas;
+};
+/**
+ * Retrieves a schema from the schemas map.
+ * @returns A schema.
+ */
+export const getSchema = (schemaName) => {
+    const schemas = getSchemas();
+    const schema = schemas.get(schemaName);
+    if (!schema) {
+        throw new Error(`Schema not found: ${schemaName}`);
+    }
+    return schema;
+};
+/**
+ * Adds a schema to the global schemas map.
+ * @param name - The name of the schema.
+ * @param value - The schema value.
+ * @ignore
+ */
+export const addSchema = (name, value) => {
+    getSchemas().set(name, value);
+};
+/**
+ * Loads a schema and compiles it into a validator.
+ * @param logger - A logger for logging information.
+ */
+export const compileAllSchemas = (logger, schemaService) => {
+    if (!schemaService) {
+        throw new Error('SchemaService needs to be defined to load schemas');
+    }
+    for (const [name, schema] of getSchemas()) {
+        schemaService.compileSchema(name, schema);
+    }
+    validateAllSchemasLoaded(logger, schemaService);
+};
+const validateAllSchemasLoaded = (logger, schemaService) => {
+    const { routesMeta } = getRoutes();
+    const validators = schemaService.getSchemaNames();
+    const missingSchemas = [];
+    for (const route of routesMeta) {
+        if (!route.input || validators.has(route.input)) {
+            continue;
+        }
+        missingSchemas.push(route.input);
+    }
+    if (missingSchemas.length > 0) {
+        logger.error(`Error: Failed to load schemas:\n.${missingSchemas.join('\n')}`);
+        logger.error('\tHave you run the schema generation?');
+        logger.error('\tnpx @pikku/cli schemas');
+    }
+    else {
+        logger.info('All schemas loaded');
+    }
+};
+export const coerceQueryStringToArray = (schemaName, data) => {
+    const schema = getSchema(schemaName);
+    for (const key in schema.properties) {
+        const property = schema.properties[key];
+        if (typeof property === 'boolean') {
+            continue;
+        }
+        const type = property.type;
+        if (typeof type === 'boolean') {
+            continue;
+        }
+        if (type === 'array' && typeof data[key] === 'string') {
+            data[key] = data[key].split(',');
+        }
+    }
+};
+export const validateAndCoerce = (logger, schemaService, schemaName, data, coerceToArray) => {
+    if (schemaService) {
+        if (!schemaName) {
+            if (data && (data.length > 0 || Object.keys(data).length > 0)) {
+                logger.warn('No schema provided, but data was passed');
+                throw new BadRequestError('No data expected');
+            }
+            else {
+                return;
+            }
+        }
+        const schema = getSchema(schemaName);
+        schemaService.compileSchema(schemaName, schema);
+        if (coerceToArray) {
+            coerceQueryStringToArray(schemaName, data);
+        }
+        schemaService.validateSchema(schemaName, data);
+    }
+};

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

@@ -0,0 +1,55 @@
+/**
+ * Interface for handling content operations.
+ */
+export interface ContentService {
+    /**
+     * Signs a content key to provide secure access.
+     * @param contentKey - The key of the content to sign.
+     * @returns A promise that resolves to the signed content key URL.
+     */
+    signContentKey: (contentKey: string, dateLessThan: Date, dateGreaterThan?: Date) => Promise<string>;
+    /**
+     * Signs a URL to provide secure access.
+     * @param url - The URL to sign.
+     * @returns A promise that resolves to the signed URL.
+     */
+    signURL: (url: string, dateLessThan: Date, dateGreaterThan?: Date) => Promise<string>;
+    /**
+     * Gets an upload URL for a file.
+     * @param fileKey - The key of the file to upload.
+     * @param contentType - The content type of the file.
+     * @returns A promise that resolves to an object containing the upload URL and asset key.
+     *  This method generates an upload URL for the specified file key and content type, allowing the file to be uploaded.
+     */
+    getUploadURL: (fileKey: string, contentType: string) => Promise<{
+        uploadUrl: string;
+        assetKey: string;
+    }>;
+    /**
+     * Deletes a file.
+     * @param fileName - The name of the file to delete.
+     * @returns A promise that resolves to a boolean indicating success.
+     *  This method deletes the specified file and returns a boolean indicating whether the deletion was successful.
+     */
+    deleteFile?: (fileName: string) => Promise<boolean>;
+    /**
+     * Writes a file.
+     * @param assetKey - The key of the asset to write.
+     * @param buffer - The buffer containing the file data.
+     * @returns A promise that resolves to a boolean indicating success.
+     */
+    writeFile?: (assetKey: string, buffer: Buffer) => Promise<boolean>;
+    /**
+     * This method copies the file from the specified absolute path to the location identified by the asset key and returns a boolean indicating success.
+     * @param assetKey - The key of the asset to copy.
+     * @param fromAbsolutePath - The absolute path of the source file.
+     * @returns A promise that resolves to a boolean indicating success.
+     */
+    copyFile?: (assetKey: string, fromAbsolutePath: string) => Promise<boolean>;
+    /**
+     * Reads a file.
+     * @param assetKey - The key of the asset to read.
+     * @returns A promise that resolves to a buffer containing the file data.
+     */
+    readFile?: (assetKey: string) => Promise<Buffer>;
+}

package/dist/services/content-service.js

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

package/dist/services/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module @pikku/core
+ */
+export * from './content-service.js';
+export * from './jwt-service.js';
+export * from './logger.js';
+export * from './logger-console.js';
+export * from './secret-service.js';
+export * from './variables-service.js';
+export * from './schema-service.js';
+export * from './local-secrets.js';
+export * from './local-variables.js';

package/dist/services/index.js

@@ -0,0 +1,14 @@
+/**
+ * @module @pikku/core
+ */
+// Interfaces
+export * from './content-service.js';
+export * from './jwt-service.js';
+export * from './logger.js';
+export * from './logger-console.js';
+export * from './secret-service.js';
+export * from './variables-service.js';
+export * from './schema-service.js';
+// Local implementations
+export * from './local-secrets.js';
+export * from './local-variables.js';