@pikku/core 0.6.9

package/src/permissions.test.ts

@@ -0,0 +1,58 @@
+import { test, describe } from 'node:test'
+import assert from 'assert'
+import { getErrorResponse, addError } from './errors/error-handler.js'
+import {
+  ForbiddenError,
+  BadRequestError,
+  NotFoundError,
+} from './errors/errors.js'
+
+describe('getErrorResponse', () => {
+  test('should return the correct error response for BadRequestError', () => {
+    const error = new BadRequestError()
+    const response = getErrorResponse(error)
+    assert.deepStrictEqual(response, {
+      status: 400,
+      message:
+        'The server cannot or will not process the request due to client error (e.g., malformed request syntax).',
+    })
+  })
+
+  test('should return the correct error response for NotFoundError', () => {
+    const error = new NotFoundError()
+    const response = getErrorResponse(error)
+    assert.deepStrictEqual(response, {
+      status: 404,
+      message: 'The server cannot find the requested resource.',
+    })
+  })
+
+  test('should return the correct error response for ForbiddenError', () => {
+    const error = new ForbiddenError()
+    const response = getErrorResponse(error)
+    assert.deepStrictEqual(response, {
+      status: 403,
+      message:
+        'The client does not have permission to access the requested resource.',
+    })
+  })
+
+  test('should return undefined for an unknown error', () => {
+    class UnknownError extends Error {}
+    const error = new UnknownError()
+    const response = getErrorResponse(error)
+    assert.strictEqual(response, undefined)
+  })
+
+  test('should return the correct error response for a custom error added to apiErrors', () => {
+    class CustomError extends Error {}
+    const customError = new CustomError()
+    const customErrorDetails = { status: 400, message: 'Custom Error' }
+
+    // Add the custom error to the apiErrors map
+    addError(CustomError, customErrorDetails)
+
+    const response = getErrorResponse(customError)
+    assert.deepStrictEqual(response, customErrorDetails)
+  })
+})

package/src/permissions.ts

@@ -0,0 +1,45 @@
+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 const verifyPermissions = async (
+  permissions:
+    | Record<string, CoreAPIPermission<any>[] | CoreAPIPermission<any>>
+    | undefined,
+  services: CoreServices,
+  data: any,
+  session?: CoreUserSession
+): Promise<boolean> => {
+  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/src/pikku-request.ts

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

package/src/pikku-response.ts

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

package/src/scheduler/index.ts

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

package/src/scheduler/log-schedulers.ts

@@ -0,0 +1,20 @@
+import { Logger } from '../services/index.js'
+import { getScheduledTasks } from './scheduler-runner.js'
+
+/**
+ * Logs all the loaded scheduled tasks.
+ * @param logger - A logger for logging information.
+ */
+export const logSchedulers = (logger: 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/src/scheduler/scheduler-runner.ts

@@ -0,0 +1,132 @@
+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'
+
+import { getErrorResponse } from '../errors/error-handler.js'
+import { closeSessionServices } from '../utils.js'
+
+export type RunScheduledTasksParams = {
+  name: string
+  session?: CoreUserSession
+  singletonServices: CoreSingletonServices
+  createSessionServices?: CreateSessionServices<
+    CoreSingletonServices,
+    CoreServices<CoreSingletonServices>,
+    CoreUserSession
+  >
+}
+
+if (!global.pikku?.scheduledTasks) {
+  global.pikku = global.pikku || {}
+  global.pikku.scheduledTasks = new Map<string, CoreScheduledTask>()
+  global.pikku.scheduledTasksMeta = []
+}
+
+const scheduledTasks = (): Map<string, CoreScheduledTask> => {
+  return global.pikku.scheduledTasks
+}
+
+const scheduledTasksMeta = (data?: ScheduledTasksMeta) => {
+  if (data) {
+    global.pikku.scheduledTasksMeta = data
+  }
+  return global.pikku.scheduledTasksMeta
+}
+
+export const addScheduledTask = <
+  APIFunction extends CoreAPIFunctionSessionless<void, void>,
+>(
+  scheduledTask: CoreScheduledTask<APIFunction>
+) => {
+  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(_scheduledTasksMeta)
+}
+
+/**
+ * Returns all the cron jobs
+ * @internal
+ */
+export const getScheduledTasks = () => {
+  return {
+    scheduledTasks: scheduledTasks(),
+    scheduledTasksMeta: scheduledTasksMeta(),
+  }
+}
+
+class ScheduledTaskNotFoundError extends Error {
+  constructor(title: string) {
+    super(`Scheduled task not found: ${title}`)
+  }
+}
+
+export async function runScheduledTask<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+  Services extends
+    CoreServices<SingletonServices> = CoreServices<SingletonServices>,
+>({
+  name,
+  session,
+  singletonServices,
+  createSessionServices,
+}: RunScheduledTasksParams): Promise<void> {
+  let sessionServices: CoreServices | undefined
+  const trackerId: string = 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: any) {
+    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/src/scheduler/scheduler.types.ts

@@ -0,0 +1,27 @@
+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/src/schema.test.ts

@@ -0,0 +1,57 @@
+import { test, describe, before } from 'node:test'
+import * as assert from 'assert'
+import { addSchema, coerceQueryStringToArray } from './schema.js'
+
+describe('Schema', () => {
+  describe('coerceQueryStringToArray', () => {
+    before(() => {
+      // Add schemas dynamically using addSchema
+      addSchema('testSchema', {
+        properties: {
+          tags: { type: 'array' },
+          count: { type: 'number' },
+          name: { type: 'string' },
+        },
+      })
+
+      addSchema('booleanSchema', {
+        properties: {
+          isActive: true, // Invalid schema definition, but the function should handle it
+          tags: { type: 'array' },
+        },
+      })
+    })
+
+    test('should split a string into an array for properties of type array', () => {
+      const data = { tags: 'a,b,c' }
+      coerceQueryStringToArray('testSchema', data)
+      assert.deepStrictEqual(data.tags, ['a', 'b', 'c'])
+    })
+
+    test('should not modify properties of type array if they are already arrays', () => {
+      const data = { tags: ['a', 'b', 'c'] }
+      coerceQueryStringToArray('testSchema', data)
+      assert.deepStrictEqual(data.tags, ['a', 'b', 'c'])
+    })
+
+    test('should not modify properties that are not type array', () => {
+      const data = { count: 5, name: 'example' }
+      coerceQueryStringToArray('testSchema', data)
+      assert.strictEqual(data.count, 5)
+      assert.strictEqual(data.name, 'example')
+    })
+
+    test('should handle cases where the data object does not have a key present in the schema', () => {
+      const data = { unknownKey: 'shouldRemain' }
+      coerceQueryStringToArray('testSchema', data)
+      assert.strictEqual(data.unknownKey, 'shouldRemain')
+    })
+
+    test('should handle cases where schema properties contain boolean values', () => {
+      const data = { tags: 'a,b,c', isActive: 'true' }
+      coerceQueryStringToArray('booleanSchema', data)
+      assert.deepStrictEqual(data.tags, ['a', 'b', 'c'])
+      assert.strictEqual(data.isActive, 'true') // No coercion should happen
+    })
+  })
+})

package/src/schema.ts

@@ -0,0 +1,124 @@
+import { Logger } from './services/logger.js'
+import { getRoutes } from './http/http-route-runner.js'
+import { SchemaService } from './services/schema-service.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<string, any>()
+  }
+  return global.pikkuSchemas
+}
+
+/**
+ * Retrieves a schema from the schemas map.
+ * @returns A schema.
+ */
+export const getSchema = (schemaName: string): any => {
+  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: string, value: any) => {
+  getSchemas().set(name, value)
+}
+
+/**
+ * Loads a schema and compiles it into a validator.
+ * @param logger - A logger for logging information.
+ */
+export const compileAllSchemas = (
+  logger: Logger,
+  schemaService?: 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: Logger,
+  schemaService: SchemaService
+) => {
+  const { routesMeta } = getRoutes()
+  const validators = schemaService.getSchemaNames()
+
+  const missingSchemas: string[] = []
+
+  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: string, data: any) => {
+  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: Logger,
+  schemaService: SchemaService | undefined,
+  schemaName: string | undefined | null,
+  data: any,
+  coerceToArray: boolean
+) => {
+  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/src/services/content-service.ts

@@ -0,0 +1,69 @@
+/**
+ * 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/src/services/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @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'

package/src/services/jwt-service.ts

@@ -0,0 +1,36 @@
+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/src/services/local-content.ts

@@ -0,0 +1,39 @@
+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 abstract class LocalContent implements ContentService {
+  constructor(_config: LocalContentConfig, _logger: Logger) {}
+
+  public abstract getUploadURL: (
+    fileKey: string,
+    contentType: string
+  ) => Promise<{ uploadUrl: string; assetKey: string }>
+
+  /**
+   * Initializes the local content service.
+   */
+  public 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.
+   */
+  public 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.
+   */
+  public abstract signContentKey(assetKey: string): Promise<string>
+}