@pikku/core 0.12.4 → 0.12.6

package/src/wirings/scheduler/scheduler-runner.ts

@@ -0,0 +1,133 @@
+import type { PikkuWire, CoreUserSession } from '../../types/core.types.js'
+import type { CoreScheduledTask } from './scheduler.types.js'
+import { getErrorResponse, PikkuError } from '../../errors/error-handler.js'
+import { PikkuMissingMetaError } from '../../errors/errors.js'
+import {
+  getSingletonServices,
+  getCreateWireServices,
+  pikkuState,
+} from '../../pikku-state.js'
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../services/user-session-service.js'
+import type {
+  CorePikkuFunctionConfig,
+  CorePikkuFunctionSessionless,
+} from '../../function/functions.types.js'
+
+export type RunScheduledTasksParams = {
+  name: string
+  session?: CoreUserSession
+}
+
+export const wireScheduler = <
+  PikkuFunctionConfig extends CorePikkuFunctionConfig<
+    CorePikkuFunctionSessionless<void, void>
+  >,
+>(
+  scheduledTask: CoreScheduledTask<PikkuFunctionConfig>
+) => {
+  const meta = pikkuState(null, 'scheduler', 'meta')
+  const taskMeta = meta[scheduledTask.name]
+  if (!taskMeta) {
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for scheduled task '${scheduledTask.name}'`
+    )
+  }
+  addFunction(taskMeta.pikkuFuncId, {
+    func: scheduledTask.func.func,
+    auth: scheduledTask.func.auth,
+    permissions: scheduledTask.func.permissions,
+    middleware: scheduledTask.func.middleware,
+    tags: scheduledTask.func.tags,
+  })
+
+  const tasks = pikkuState(null, 'scheduler', 'tasks')
+  if (tasks.has(scheduledTask.name)) {
+    throw new Error(`Scheduled task already exists: ${scheduledTask.name}`)
+  }
+  tasks.set(scheduledTask.name, scheduledTask)
+}
+
+class ScheduledTaskNotFoundError extends PikkuError {
+  constructor(title: string) {
+    super(`Scheduled task not found: ${title}`)
+  }
+}
+
+class ScheduledTaskSkippedError extends PikkuError {
+  constructor(taskName: string, reason?: string) {
+    super(
+      `Scheduled task '${taskName}' was skipped${reason ? `: ${reason}` : ''}`
+    )
+    this.name = 'ScheduledTaskSkippedError'
+  }
+}
+
+export async function runScheduledTask({
+  name,
+  session,
+}: RunScheduledTasksParams): Promise<void> {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
+  const task = pikkuState(null, 'scheduler', 'tasks').get(name)
+  const meta = pikkuState(null, 'scheduler', 'meta')[name]
+
+  const userSession = new PikkuSessionService()
+  if (session) {
+    userSession.set(session)
+  }
+
+  if (!task) {
+    throw new ScheduledTaskNotFoundError(`Scheduled task not found: ${name}`)
+  }
+  if (!meta) {
+    throw new ScheduledTaskNotFoundError(
+      `Scheduled task meta not found: ${name}`
+    )
+  }
+
+  // Create the scheduled task wire object
+  const wire: PikkuWire = {
+    scheduledTask: {
+      name,
+      schedule: task.schedule,
+      executionTime: new Date(),
+      skip: (reason?: string) => {
+        throw new ScheduledTaskSkippedError(name, reason)
+      },
+    },
+    ...createMiddlewareSessionWireProps(userSession),
+  }
+
+  try {
+    singletonServices.logger.info(
+      `Running schedule task: ${name} | schedule: ${task.schedule}`
+    )
+
+    await runPikkuFunc('scheduler', meta.name, meta.pikkuFuncId, {
+      singletonServices,
+      createWireServices,
+      auth: false,
+      data: () => undefined,
+      inheritedMiddleware: meta.middleware,
+      wireMiddleware: task.middleware,
+      tags: task.tags,
+      wire,
+      sessionService: userSession,
+      packageName: meta.packageName,
+    })
+  } catch (e: any) {
+    const errorResponse = getErrorResponse(e)
+    if (errorResponse != null) {
+      singletonServices.logger.error(e)
+    }
+    throw e
+  }
+}
+
+export const getScheduledTasks = () => {
+  return pikkuState(null, 'scheduler', 'tasks')
+}

package/src/wirings/scheduler/scheduler.types.ts

@@ -0,0 +1,53 @@
+import type {
+  CoreUserSession,
+  CorePikkuMiddleware,
+  CommonWireMeta,
+} from '../../types/core.types.js'
+import type {
+  CorePikkuFunctionConfig,
+  CorePikkuFunctionSessionless,
+} from '../../function/functions.types.js'
+
+/**
+ * Represents metadata for scheduled tasks, including title, schedule, and documentation.
+ */
+export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> =
+  Record<
+    string,
+    CommonWireMeta & {
+      name: string
+      schedule: string
+      session?: UserSession
+    }
+  >
+
+/**
+ * Represents a core scheduled task.
+ */
+export type CoreScheduledTask<
+  PikkuFunctionConfig = CorePikkuFunctionConfig<
+    CorePikkuFunctionSessionless<void, void>
+  >,
+  PikkuMiddleware = CorePikkuMiddleware<any>,
+> = {
+  name: string
+  schedule: string
+  func: PikkuFunctionConfig
+  tags?: string[]
+  middleware?: PikkuMiddleware[]
+}
+
+/**
+ * Represents a scheduled task wire object for middleware
+ * Provides information about the current scheduled task execution
+ */
+export interface PikkuScheduledTask {
+  /** The name of the scheduled task being executed */
+  name: string
+  /** The cron schedule expression */
+  schedule: string
+  /** Current execution timestamp */
+  executionTime: Date
+  /** Skip the current task execution */
+  skip: (reason?: string) => void
+}

package/src/wirings/secret/index.ts

@@ -0,0 +1,9 @@
+export { wireSecret } from './secret.types.js'
+export type {
+  CoreSecret,
+  OAuth2CredentialConfig,
+  SecretDefinitionMeta,
+  SecretDefinitionsMeta,
+  SecretDefinitions,
+} from './secret.types.js'
+export { validateAndBuildSecretDefinitionsMeta } from './validate-secret-definitions.js'

package/src/wirings/secret/secret.types.ts

@@ -0,0 +1,32 @@
+export type CoreSecret<T = unknown> = {
+  name: string
+  displayName: string
+  description?: string
+  secretId: string
+  schema: T
+}
+
+export type OAuth2CredentialConfig = {
+  tokenSecretId: string
+  authorizationUrl: string
+  tokenUrl: string
+  scopes: string[]
+  pkce?: boolean
+  additionalParams?: Record<string, string>
+}
+
+export type SecretDefinitionMeta = {
+  name: string
+  displayName: string
+  description?: string
+  secretId: string
+  schema?: Record<string, unknown> | string
+  oauth2?: OAuth2CredentialConfig
+  sourceFile?: string
+}
+
+export type SecretDefinitionsMeta = Record<string, SecretDefinitionMeta>
+
+export type SecretDefinitions = SecretDefinitionMeta[]
+
+export const wireSecret = <T>(_config: CoreSecret<T>): void => {}

package/src/wirings/secret/validate-secret-definitions.test.ts

@@ -0,0 +1,140 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { validateAndBuildSecretDefinitionsMeta } from './validate-secret-definitions.js'
+
+describe('validateAndBuildSecretDefinitionsMeta', () => {
+  test('should build meta from single definition', () => {
+    const definitions = [
+      {
+        name: 'stripe',
+        displayName: 'Stripe',
+        description: 'API key',
+        secretId: 'STRIPE_KEY',
+        sourceFile: 'a.ts',
+      },
+    ]
+    const result = validateAndBuildSecretDefinitionsMeta(
+      definitions as any,
+      new Map()
+    )
+    assert.ok(result['stripe'])
+    assert.strictEqual(result['stripe'].secretId, 'STRIPE_KEY')
+    assert.strictEqual(result['stripe'].displayName, 'Stripe')
+  })
+
+  test('should allow duplicate secretId with same schema', () => {
+    const schemaLookup = new Map([
+      ['schema1', { variableName: 'Schema', sourceFile: 'types.ts' }],
+    ])
+    const definitions = [
+      {
+        name: 'cred1',
+        displayName: 'Cred 1',
+        description: 'd',
+        secretId: 'SHARED',
+        schema: 'schema1',
+        sourceFile: 'a.ts',
+      },
+      {
+        name: 'cred2',
+        displayName: 'Cred 2',
+        description: 'd',
+        secretId: 'SHARED',
+        schema: 'schema1',
+        sourceFile: 'b.ts',
+      },
+    ]
+    const result = validateAndBuildSecretDefinitionsMeta(
+      definitions as any,
+      schemaLookup
+    )
+    assert.ok(result['cred1'])
+    assert.ok(result['cred2'])
+  })
+
+  test('should throw when duplicate secretId has different schemas', () => {
+    const schemaLookup = new Map([
+      ['schema1', { variableName: 'SchemaA', sourceFile: 'types.ts' }],
+      ['schema2', { variableName: 'SchemaB', sourceFile: 'types2.ts' }],
+    ])
+    const definitions = [
+      {
+        name: 'cred1',
+        displayName: 'Cred 1',
+        description: 'd',
+        secretId: 'SHARED',
+        schema: 'schema1',
+        sourceFile: 'a.ts',
+      },
+      {
+        name: 'cred2',
+        displayName: 'Cred 2',
+        description: 'd',
+        secretId: 'SHARED',
+        schema: 'schema2',
+        sourceFile: 'b.ts',
+      },
+    ]
+    assert.throws(
+      () =>
+        validateAndBuildSecretDefinitionsMeta(definitions as any, schemaLookup),
+      (err: any) => err.message.includes('different schemas')
+    )
+  })
+
+  test('should throw when duplicate secretId has different oauth2 configs', () => {
+    const definitions = [
+      {
+        name: 'cred1',
+        displayName: 'C1',
+        description: 'd',
+        secretId: 'OAUTH',
+        oauth2: { provider: 'google' },
+        sourceFile: 'a.ts',
+      },
+      {
+        name: 'cred2',
+        displayName: 'C2',
+        description: 'd',
+        secretId: 'OAUTH',
+        oauth2: { provider: 'github' },
+        sourceFile: 'b.ts',
+      },
+    ]
+    assert.throws(
+      () =>
+        validateAndBuildSecretDefinitionsMeta(definitions as any, new Map()),
+      (err: any) => err.message.includes('different configurations')
+    )
+  })
+
+  test('should handle empty definitions', () => {
+    const result = validateAndBuildSecretDefinitionsMeta([], new Map())
+    assert.deepStrictEqual(result, {})
+  })
+
+  test('should not duplicate names in meta', () => {
+    const definitions = [
+      {
+        name: 'same',
+        displayName: 'Same',
+        description: 'd',
+        secretId: 'KEY1',
+        sourceFile: 'a.ts',
+      },
+      {
+        name: 'same',
+        displayName: 'Same',
+        description: 'd',
+        secretId: 'KEY2',
+        sourceFile: 'b.ts',
+      },
+    ]
+    const result = validateAndBuildSecretDefinitionsMeta(
+      definitions as any,
+      new Map()
+    )
+    assert.ok(result['same'])
+    assert.strictEqual(result['same'].secretId, 'KEY1')
+  })
+})

package/src/wirings/secret/validate-secret-definitions.ts

@@ -0,0 +1,82 @@
+import type {
+  SecretDefinitions,
+  SecretDefinitionsMeta,
+} from './secret.types.js'
+
+export interface SchemaRefLike {
+  variableName: string
+  sourceFile: string
+}
+
+export function validateAndBuildSecretDefinitionsMeta(
+  definitions: SecretDefinitions,
+  schemaLookup: Map<string, SchemaRefLike>
+): SecretDefinitionsMeta {
+  const meta: SecretDefinitionsMeta = {}
+  const secretIdToDefinition: Map<string, SecretDefinitions[0]> = new Map()
+
+  for (const def of definitions) {
+    const existingDef = secretIdToDefinition.get(def.secretId)
+
+    if (existingDef) {
+      if (def.schema && existingDef.schema) {
+        const defSchemaRef = schemaLookup.get(def.schema as string)
+        const existingSchemaRef = schemaLookup.get(existingDef.schema as string)
+
+        if (defSchemaRef && existingSchemaRef) {
+          if (
+            defSchemaRef.variableName !== existingSchemaRef.variableName ||
+            defSchemaRef.sourceFile !== existingSchemaRef.sourceFile
+          ) {
+            throw new Error(
+              `Secret '${def.secretId}' is defined with different schemas.\n` +
+                `  First definition: ${existingDef.sourceFile} (schema: ${existingSchemaRef.variableName})\n` +
+                `  Second definition: ${def.sourceFile} (schema: ${defSchemaRef.variableName})\n` +
+                `Credentials sharing a secretId must use the same schema.`
+            )
+          }
+        }
+      }
+
+      if (def.oauth2 && existingDef.oauth2) {
+        if (JSON.stringify(def.oauth2) !== JSON.stringify(existingDef.oauth2)) {
+          throw new Error(
+            `OAuth2 secret '${def.secretId}' is defined with different configurations.\n` +
+              `  First definition: ${existingDef.sourceFile}\n` +
+              `  Second definition: ${def.sourceFile}\n` +
+              `Credentials sharing a secretId must use the same configuration.`
+          )
+        }
+      }
+
+      if (!meta[def.name]) {
+        meta[def.name] = {
+          name: def.name,
+          displayName: def.displayName,
+          description: def.description,
+          secretId: def.secretId,
+          schema: def.schema,
+          oauth2: def.oauth2,
+          sourceFile: def.sourceFile,
+        }
+      }
+      continue
+    }
+
+    secretIdToDefinition.set(def.secretId, def)
+
+    if (!meta[def.name]) {
+      meta[def.name] = {
+        name: def.name,
+        displayName: def.displayName,
+        description: def.description,
+        secretId: def.secretId,
+        schema: def.schema,
+        oauth2: def.oauth2,
+        sourceFile: def.sourceFile,
+      }
+    }
+  }
+
+  return meta
+}

package/src/wirings/trigger/index.ts

@@ -0,0 +1,10 @@
+export { wireTrigger, wireTriggerSource } from './trigger-runner.js'
+export { PikkuTriggerService } from './pikku-trigger-service.js'
+export type {
+  TriggerMeta,
+  TriggerSourceMeta,
+  CorePikkuTriggerFunction,
+  CorePikkuTriggerFunctionConfig,
+  CoreTrigger,
+  PikkuTrigger,
+} from './trigger.types.js'

package/src/wirings/trigger/pikku-trigger-service.ts

@@ -0,0 +1,112 @@
+import { rpcService } from '../rpc/rpc-runner.js'
+import { setupTrigger } from './trigger-runner.js'
+import type { TriggerInstance } from './trigger.types.js'
+import type { TriggerService } from '../../services/trigger-service.js'
+import {
+  getSingletonServices,
+  getCreateWireServices,
+  pikkuState,
+} from '../../pikku-state.js'
+
+export type TriggerTarget = {
+  targetType: 'rpc' | 'workflow'
+  targetName: string
+  startNode?: string
+}
+
+export type TriggerSourceInfo = {
+  name: string
+  input: unknown
+}
+
+export abstract class PikkuTriggerService implements TriggerService {
+  protected activeTriggers = new Map<string, TriggerInstance>()
+
+  abstract start(): Promise<void>
+
+  async stop(): Promise<void> {
+    const singletonServices = getSingletonServices()
+    for (const [name, instance] of this.activeTriggers) {
+      try {
+        await instance.teardown()
+        singletonServices.logger.info(`Stopped trigger: ${name}`)
+      } catch (error) {
+        singletonServices.logger.error(
+          `Error stopping trigger ${name}: ${error}`
+        )
+      }
+    }
+    this.activeTriggers.clear()
+  }
+
+  protected getTriggerTargets(): Map<string, TriggerTarget[]> {
+    const triggers = pikkuState(null, 'trigger', 'triggers')
+
+    const triggerTargets = new Map<string, TriggerTarget[]>()
+
+    for (const [name] of triggers) {
+      const meta = pikkuState(null, 'trigger', 'meta')[name]
+      if (meta) {
+        if (!triggerTargets.has(name)) {
+          triggerTargets.set(name, [])
+        }
+        triggerTargets.get(name)!.push({
+          targetType: 'rpc',
+          targetName: meta.pikkuFuncId,
+        })
+      }
+    }
+
+    return triggerTargets
+  }
+
+  protected getTriggerSources(): Map<string, { input?: unknown }> {
+    return pikkuState(null, 'trigger', 'triggerSources')
+  }
+
+  protected async setupTriggerInstance(
+    name: string,
+    input: unknown,
+    onTrigger: (data: unknown) => Promise<void>
+  ): Promise<TriggerInstance> {
+    return setupTrigger({
+      name,
+      input,
+      onTrigger,
+    })
+  }
+
+  protected async onTriggerFire(
+    triggerName: string,
+    targets: TriggerTarget[],
+    data: unknown
+  ): Promise<void> {
+    const singletonServices = getSingletonServices()
+    const createWireServices = getCreateWireServices()
+    const wireServices = await createWireServices?.(singletonServices, {})
+    const services = { ...singletonServices, ...wireServices }
+    const rpc = rpcService.getContextRPCService(services, {}, false)
+
+    for (const target of targets) {
+      try {
+        if (target.targetType === 'workflow') {
+          await rpc.startWorkflow(target.targetName, data, {
+            startNode: target.startNode,
+          })
+          singletonServices.logger.info(
+            `Trigger '${triggerName}' started workflow '${target.targetName}'`
+          )
+        } else {
+          await rpc.invoke(target.targetName, data)
+          singletonServices.logger.info(
+            `Trigger '${triggerName}' invoked RPC '${target.targetName}'`
+          )
+        }
+      } catch (error) {
+        singletonServices.logger.error(
+          `Error invoking ${target.targetType} '${target.targetName}' from trigger '${triggerName}': ${error}`
+        )
+      }
+    }
+  }
+}

package/src/wirings/trigger/trigger-runner.test.ts

@@ -0,0 +1,79 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import {
+  wireTrigger,
+  wireTriggerSource,
+  getRegisteredTriggers,
+  getTriggerMeta,
+} from './trigger-runner.js'
+import { resetPikkuState, pikkuState } from '../../pikku-state.js'
+import { PikkuMissingMetaError } from '../../errors/errors.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+describe('wireTrigger', () => {
+  test('should register a trigger when meta exists', () => {
+    const meta = pikkuState(null, 'trigger', 'meta')
+    ;(meta as any)['myTrigger'] = { pikkuFuncId: 'triggerFunc' }
+
+    wireTrigger({ name: 'myTrigger', func: async () => {} } as any)
+
+    const triggers = getRegisteredTriggers()
+    assert.ok(triggers.has('myTrigger'))
+  })
+
+  test('should throw PikkuMissingMetaError when meta is missing', () => {
+    assert.throws(
+      () => wireTrigger({ name: 'noMeta', func: async () => {} } as any),
+      (err: any) => err instanceof PikkuMissingMetaError
+    )
+  })
+})
+
+describe('wireTriggerSource', () => {
+  test('should register a trigger source when meta exists', () => {
+    const sourceMeta = pikkuState(null, 'trigger', 'sourceMeta')
+    ;(sourceMeta as any)['mySource'] = { pikkuFuncId: 'sourceFunc' }
+
+    wireTriggerSource({ name: 'mySource', func: async () => {} } as any)
+
+    const sources = pikkuState(null, 'trigger', 'triggerSources')
+    assert.ok(sources.has('mySource'))
+  })
+
+  test('should throw PikkuMissingMetaError when source meta is missing', () => {
+    assert.throws(
+      () => wireTriggerSource({ name: 'noMeta', func: async () => {} } as any),
+      (err: any) => err instanceof PikkuMissingMetaError
+    )
+  })
+
+  test('should throw when trigger source already exists', () => {
+    const sourceMeta = pikkuState(null, 'trigger', 'sourceMeta')
+    ;(sourceMeta as any)['dupSource'] = { pikkuFuncId: 'sourceFunc' }
+
+    wireTriggerSource({ name: 'dupSource', func: async () => {} } as any)
+
+    assert.throws(
+      () =>
+        wireTriggerSource({ name: 'dupSource', func: async () => {} } as any),
+      { message: 'Trigger source already exists: dupSource' }
+    )
+  })
+})
+
+describe('getRegisteredTriggers', () => {
+  test('should return the triggers Map', () => {
+    const triggers = getRegisteredTriggers()
+    assert.ok(triggers instanceof Map)
+  })
+})
+
+describe('getTriggerMeta', () => {
+  test('should return the trigger meta object', () => {
+    const meta = getTriggerMeta()
+    assert.ok(typeof meta === 'object')
+  })
+})