@pikku/core 0.12.23 → 0.12.24

package/src/function/function-runner.ts

@@ -36,6 +36,7 @@ import {
   createWireServicesCredentialWireProps,
 } from '../services/credential-wire-service.js'
 import { defaultPikkuUserIdResolver } from '../services/pikku-user-id.js'
+import { resolveAuditConfig } from '../services/audit-service.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { closeWireServices } from '../utils.js'
 
@@ -288,6 +289,8 @@ export const runPikkuFunc = async <In = any, Out = any>(
     throw new Error(`Function meta not found: ${funcName}`)
   }
 
+  const resolvedFunctionId = funcMeta.pikkuFuncId ?? funcName
+
   // For addon packages, get or create their singleton services
   const resolvedSingletonServices = packageName
     ? await getOrCreatePackageSingletonServices(packageName, singletonServices)
@@ -332,6 +335,17 @@ export const runPikkuFunc = async <In = any, Out = any>(
     )
   }
 
+  const resolvedAuditConfig = resolveAuditConfig(funcConfig.audit)
+  const invocationWire = resolvedWire as PikkuWire
+  const previousFunctionId = invocationWire.functionId
+  const previousAudit = invocationWire.audit
+  const previousRpcDescriptor = Object.getOwnPropertyDescriptor(
+    invocationWire,
+    'rpc'
+  )
+  invocationWire.functionId = resolvedFunctionId
+  invocationWire.audit = resolvedAuditConfig
+
   // Convert tags to PermissionMetadata and merge with inheritedPermissions
   let mergedInheritedPermissions: PermissionMetadata[]
   if (tags && tags.length > 0) {
@@ -346,20 +360,20 @@ export const runPikkuFunc = async <In = any, Out = any>(
   // Helper function to run permissions and execute the function
   const executeFunction = async () => {
     await resolveSession(
-      resolvedWire,
+      invocationWire,
       resolvedSingletonServices,
       sessionService
     )
 
     if (sessionService) {
-      resolvedWire.session = sessionService.freezeInitial()
-      resolvedWire.setSession = (s: any) => sessionService.set(s)
-      resolvedWire.clearSession = () => sessionService.clear()
-      resolvedWire.getSession = () => sessionService.get()
-      resolvedWire.hasSessionChanged = () => sessionService.sessionChanged
+      invocationWire.session = sessionService.freezeInitial()
+      invocationWire.setSession = (s: any) => sessionService.set(s)
+      invocationWire.clearSession = () => sessionService.clear()
+      invocationWire.getSession = () => sessionService.get()
+      invocationWire.hasSessionChanged = () => sessionService.sessionChanged
     }
 
-    const session = resolvedWire.session
+    const session = invocationWire.session
 
     if (funcMeta.sessionless) {
       if (wiringAuth === true || funcConfig.auth === true) {
@@ -422,7 +436,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         funcInheritedPermissions: funcMeta.permissions,
         funcPermissions: funcConfig.permissions,
         services: resolvedSingletonServices,
-        wire: resolvedWire as any,
+        wire: invocationWire as any,
         data: actualData,
         packageName,
       })
@@ -432,23 +446,23 @@ export const runPikkuFunc = async <In = any, Out = any>(
     try {
       wireServices = (await resolvedCreateWireServices?.(
         resolvedSingletonServices,
-        resolvedWire
+        invocationWire
       )) as Record<string, unknown> | undefined
       const services =
         wireServices && Object.keys(wireServices).length > 0
           ? { ...resolvedSingletonServices, ...wireServices }
           : resolvedSingletonServices
       const callerPackageName = packageName
-      Object.defineProperty(resolvedWire, 'rpc', {
+      Object.defineProperty(invocationWire, 'rpc', {
         get() {
           const rpc = rpcService.getContextRPCService(
             services,
-            resolvedWire,
+            invocationWire,
             { sessionService },
             0,
             callerPackageName
           )
-          Object.defineProperty(resolvedWire, 'rpc', {
+          Object.defineProperty(invocationWire, 'rpc', {
             value: rpc,
             writable: true,
             configurable: true,
@@ -458,7 +472,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         configurable: true,
         enumerable: true,
       })
-      return await funcConfig.func(services, actualData, resolvedWire)
+      return await funcConfig.func(services, actualData, invocationWire)
     } finally {
       if (wireServices && Object.keys(wireServices).length > 0) {
         await closeWireServices(resolvedSingletonServices.logger, wireServices)
@@ -475,13 +489,45 @@ export const runPikkuFunc = async <In = any, Out = any>(
   })
 
   if (allMiddleware.length > 0) {
-    return (await runMiddleware<CorePikkuMiddleware>(
-      resolvedSingletonServices,
-      resolvedWire,
-      allMiddleware,
-      executeFunction
-    )) as Out
+    try {
+      return (await runMiddleware<CorePikkuMiddleware>(
+        resolvedSingletonServices,
+        invocationWire,
+        allMiddleware,
+        executeFunction
+      )) as Out
+    } finally {
+      if (previousRpcDescriptor) {
+        Object.defineProperty(invocationWire, 'rpc', previousRpcDescriptor)
+      }
+      if (previousFunctionId === undefined) {
+        delete (invocationWire as any).functionId
+      } else {
+        invocationWire.functionId = previousFunctionId
+      }
+      if (previousAudit === undefined) {
+        delete (invocationWire as any).audit
+      } else {
+        invocationWire.audit = previousAudit
+      }
+    }
   }
 
-  return (await executeFunction()) as Out
+  try {
+    return (await executeFunction()) as Out
+  } finally {
+    if (previousRpcDescriptor) {
+      Object.defineProperty(invocationWire, 'rpc', previousRpcDescriptor)
+    }
+    if (previousFunctionId === undefined) {
+      delete (invocationWire as any).functionId
+    } else {
+      invocationWire.functionId = previousFunctionId
+    }
+    if (previousAudit === undefined) {
+      delete (invocationWire as any).audit
+    } else {
+      invocationWire.audit = previousAudit
+    }
+  }
 }

package/src/function/functions.types.ts

@@ -29,7 +29,12 @@ export type CorePikkuFunction<
   Out,
   Services extends CoreSingletonServices = CoreServices,
   Session extends CoreUserSession = CoreUserSession,
-  Wire extends PikkuWire<In, Out> = PikkuWire<In, Out, true, Session>,
+  Wire extends PikkuWire<In, Out, true, Session> = PikkuWire<
+    In,
+    Out,
+    true,
+    Session
+  >,
 > = (
   services: Services,
   data: In,
@@ -74,8 +79,15 @@ export type CorePikkuFunctionSessionless<
 export type CorePikkuPermission<
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Wire extends PikkuWire<In, never, false, CoreUserSession, any, never, never> =
-    PikkuWire<In, never, false, CoreUserSession, never, never, never>,
+  Wire extends PikkuWire<In, never, false, any, any, never, never> = PikkuWire<
+    In,
+    never,
+    false,
+    any,
+    never,
+    never,
+    never
+  >,
 > = (services: Services, data: In, wire: Wire) => Promise<boolean>
 
 /**
@@ -88,11 +100,11 @@ export type CorePikkuPermission<
 export type CorePikkuPermissionConfig<
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<
+  Wire extends PikkuWire<In, never, false, any> = PikkuWire<
     In,
     never,
     false,
-    CoreUserSession
+    any
   >,
 > = {
   /** The permission function */
@@ -131,10 +143,8 @@ export type CorePikkuPermissionConfig<
 export const pikkuPermission = <
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Wire extends PickRequired<
-    PikkuWire<In, never, false, CoreUserSession>,
-    'session'
-  > = PickRequired<PikkuWire<In, never, false, CoreUserSession>, 'session'>,
+  Wire extends PickRequired<PikkuWire<In, never, false, any>, 'session'> =
+    PickRequired<PikkuWire<In, never, false, any>, 'session'>,
 >(
   permission:
     | CorePikkuPermission<In, Services, Wire>
@@ -154,11 +164,11 @@ export const pikkuPermission = <
 export type CorePikkuPermissionFactory<
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<
+  Wire extends PikkuWire<In, never, false, any> = PikkuWire<
     In,
     never,
     false,
-    CoreUserSession
+    any
   >,
 > = (input: In) => CorePikkuPermission<any, Services, Wire>
 
@@ -285,6 +295,11 @@ export type CorePikkuFunctionConfig<
   readonly?: boolean
   deploy?: 'serverless' | 'server' | 'auto'
   approvalRequired?: boolean
+  audit?:
+    | boolean
+    | {
+        durability?: 'best-effort' | 'transactional'
+      }
   approvalDescription?: any
   func: PikkuFunction
   auth?: boolean

package/src/index.ts

@@ -96,6 +96,15 @@ export { NotFoundError } from './errors/errors.js'
 export type { EventHubService } from './wirings/channel/eventhub-service.js'
 export type { QueueService } from './wirings/queue/queue.types.js'
 export type { JWTService } from './services/jwt-service.js'
+export type {
+  EmailService,
+  EmailTemplateReference,
+  SendEmailInput,
+  SendEmailResult,
+  SendHTMLEmailInput,
+  SendTemplateEmailInput,
+  SendTextEmailInput,
+} from './services/email-service.js'
 export type { SecretService } from './services/secret-service.js'
 export type { VariablesService } from './services/variables-service.js'
 export type {
@@ -114,9 +123,35 @@ export type { GatewayService } from './services/gateway-service.js'
 export type { TriggerService } from './services/trigger-service.js'
 export type { SchemaService } from './services/schema-service.js'
 export type { SessionService } from './services/user-session-service.js'
+export {
+  NoopAuditService,
+  createInvocationAudit,
+  resolveAuditActorFromWire,
+  resolveAuditConfig,
+} from './services/audit-service.js'
+export type {
+  AuditActor,
+  AuditConfig,
+  AuditDurability,
+  AuditEvent,
+  AuditEventBatch,
+  AuditLog,
+  AuditLogWriteInput,
+  AuditOutcome,
+  AuditService,
+  AuditSource,
+  ResolvedAuditConfig,
+} from './services/audit-service.js'
 export type { AIAgentRunnerService } from './services/ai-agent-runner-service.js'
 export type { AIRunStateService } from './services/ai-run-state-service.js'
 export type { AIStorageService } from './services/ai-storage-service.js'
+export type {
+  EmailsMeta,
+  EmailTemplateMeta,
+  EmailTemplateLocaleMeta,
+  EmailTemplateAssets,
+  MetaService,
+} from './services/meta-service.js'
 export type { HTTPMethod } from './wirings/http/http.types.js'
 export type { GraphNodeConfig } from './wirings/workflow/graph/workflow-graph.types.js'
 export { createGraph } from './wirings/workflow/graph/graph-node.js'

package/src/middleware-runner.ts

@@ -1,6 +1,4 @@
 import type {
-  CoreSingletonServices,
-  PikkuWire,
   CorePikkuMiddleware,
   CorePikkuMiddlewareGroup,
   PikkuWiringTypes,
@@ -18,16 +16,16 @@ const PRIORITY_ORDER: Record<MiddlewarePriority, number> = {
   lowest: 4,
 }
 
-const getMiddlewarePriority = (fn: CorePikkuMiddleware): number => {
+const getMiddlewarePriority = (fn: CorePikkuMiddleware<any, any>): number => {
   const priority = (
-    fn as CorePikkuMiddleware & { __priority?: MiddlewarePriority }
+    fn as CorePikkuMiddleware<any, any> & { __priority?: MiddlewarePriority }
   ).__priority
   return PRIORITY_ORDER[priority ?? 'medium']
 }
 
 const sortByPriority = (
-  middlewares: CorePikkuMiddleware[]
-): CorePikkuMiddleware[] => {
+  middlewares: CorePikkuMiddleware<any, any>[]
+): CorePikkuMiddleware<any, any>[] => {
   return middlewares.sort(
     (a, b) => getMiddlewarePriority(a) - getMiddlewarePriority(b)
   )
@@ -50,9 +48,11 @@ const sortByPriority = (
  *   async () => { return await runMain(); }
  * );
  */
-export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
-  services: CoreSingletonServices,
-  wire: PikkuWire,
+export const runMiddleware = async <
+  Middleware extends CorePikkuMiddleware<any, any>,
+>(
+  services: Parameters<Middleware>[0],
+  wire: Parameters<Middleware>[1],
   middlewares: readonly Middleware[],
   main?: () => Promise<unknown>
 ): Promise<unknown> => {
@@ -77,7 +77,7 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
 }
 
 const isSortedByPriority = (
-  middlewares: readonly CorePikkuMiddleware[]
+  middlewares: readonly CorePikkuMiddleware<any, any>[]
 ): boolean => {
   for (let i = 1; i < middlewares.length; i++) {
     if (

package/src/permissions.ts

@@ -24,7 +24,7 @@ const verifyPermissions = async <Out = any>(
   permissions: CorePermissionGroup,
   services: CoreServices,
   data: any,
-  wire: PikkuWire<any, never, any, never, never, never>
+  wire: PikkuWire<any, never, any, CoreUserSession, never, never, never>
 ): Promise<boolean> => {
   if (!permissions) {
     return true
@@ -311,7 +311,7 @@ export const runPermissions = async (
     funcInheritedPermissions?: PermissionMetadata[]
     funcPermissions?: CorePermissionGroup | CorePikkuPermission[]
     services: CoreServices
-    wire: PikkuWire<any, never, any, never, never, never>
+    wire: PikkuWire<any, never, any, CoreUserSession, never, never, never>
     data: any
     packageName?: string | null
   }
@@ -377,13 +377,13 @@ export const checkAuthPermissions = async (
     any,
     never,
     any,
-    never,
+    CoreUserSession,
     never,
     never
   >
 
   // Extract only pikkuAuth permissions (marked with __pikkuAuth)
-  const authPerms: CorePikkuPermission[] = []
+  const authPerms: CorePikkuPermission<any, any, any>[] = []
   for (const permission of allPermissions) {
     if (typeof permission === 'function') {
       if ((permission as any).__pikkuAuth) {

package/src/services/ai-agent-runner-service.ts

@@ -42,4 +42,7 @@ export interface AIAgentRunnerService {
     channel: AIStreamChannel
   ): Promise<AIAgentStepResult>
   run(params: AIAgentRunnerParams): Promise<AIAgentStepResult>
+  /** Return a new runner that uses the given API key for every LLM call.
+   *  Optional — runners that don't support per-key scoping leave this undefined. */
+  withApiKey?(apiKey: string): AIAgentRunnerService
 }

package/src/services/audit-service.test.ts

@@ -0,0 +1,44 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  createInvocationAudit,
+  type AuditEvent,
+  type AuditEventBatch,
+} from './audit-service.js'
+
+describe('audit-service', () => {
+  test('best-effort flush failures are logged and do not throw', async () => {
+    const warnings: unknown[][] = []
+    const audit = createInvocationAudit(
+      {
+        async audit(_event: AuditEvent): Promise<void> {
+          throw new Error('should not use single-event write')
+        },
+        async write(_batch: AuditEventBatch): Promise<void> {
+          throw new Error('sink failed')
+        },
+      },
+      {
+        wireType: 'rpc',
+        wireId: 'wire-best-effort',
+        functionId: 'bestEffortFunc',
+        audit: { durability: 'best-effort' },
+        logger: {
+          warn: (...args: unknown[]) => warnings.push(args),
+        },
+      } as any
+    )
+
+    await audit.write({
+      type: 'db.query',
+      source: 'auto',
+      queryId: 'q-1',
+    })
+
+    await assert.doesNotReject(async () => {
+      await audit.close()
+    })
+    assert.equal(warnings.length, 1)
+    assert.equal(warnings[0]?.[0], 'best-effort audit flush failed')
+  })
+})

package/src/services/audit-service.ts

@@ -0,0 +1,198 @@
+import type {
+  CoreUserSession,
+  PikkuWire,
+  PikkuWiringTypes,
+} from '../types/core.types.js'
+
+export type AuditDurability = 'best-effort' | 'transactional'
+export type AuditOutcome = 'success' | 'failed' | 'denied'
+export type AuditSource = 'auto' | 'explicit'
+
+export type AuditConfig =
+  | boolean
+  | {
+      durability?: AuditDurability
+    }
+
+export type ResolvedAuditConfig = {
+  durability: AuditDurability
+}
+
+export type AuditActor = {
+  userId?: string
+  orgId?: string
+  pikkuUserId?: string
+}
+
+export type AuditEvent = {
+  eventId?: string
+  type: string
+  source: AuditSource
+  outcome?: AuditOutcome
+  occurredAt: string
+  functionId?: string
+  wireType?: PikkuWiringTypes
+  wireId?: string
+  traceId?: string
+  transactionId?: string | null
+  queryId?: string | null
+  actor?: AuditActor
+  input?: unknown
+  metadata?: Record<string, unknown>
+}
+
+export type AuditEventBatch = AuditEvent[]
+
+export interface AuditService {
+  audit(event: AuditEvent): Promise<void>
+  write?(batch: AuditEventBatch): Promise<void>
+}
+
+export class NoopAuditService implements AuditService {
+  async audit(_event: AuditEvent): Promise<void> {}
+
+  async write(_batch: AuditEventBatch): Promise<void> {}
+}
+
+export type AuditLogWriteInput = Omit<AuditEvent, 'occurredAt'>
+
+export interface AuditLog {
+  readonly config: ResolvedAuditConfig | undefined
+  write(event: AuditLogWriteInput): Promise<void>
+  flush(): Promise<void>
+  close(): Promise<void>
+}
+
+class DisabledInvocationAudit implements AuditLog {
+  public readonly config = undefined
+  private warned = false
+
+  constructor(
+    private readonly wire: PikkuWire<any, any, any, CoreUserSession>
+  ) {}
+
+  async write(_event: AuditLogWriteInput): Promise<void> {
+    if (!this.warned) {
+      this.warned = true
+      ;(this.wire as any).logger?.warn?.(
+        'audit.write() called for an invocation without wire.audit enabled'
+      )
+    }
+  }
+
+  async flush(): Promise<void> {}
+
+  async close(): Promise<void> {}
+}
+
+class InvocationAuditLog implements AuditLog {
+  private readonly buffer: AuditEvent[] = []
+
+  constructor(
+    public readonly config: ResolvedAuditConfig,
+    private readonly service: AuditService,
+    private readonly wire: PikkuWire<any, any, any, CoreUserSession>
+  ) {}
+
+  async write(event: AuditLogWriteInput): Promise<void> {
+    const resolved = this.resolveEvent(event)
+
+    if (this.config.durability === 'transactional') {
+      await this.service.audit(resolved)
+      return
+    }
+
+    this.buffer.push(resolved)
+  }
+
+  async flush(): Promise<void> {
+    if (
+      this.config.durability === 'transactional' ||
+      this.buffer.length === 0
+    ) {
+      return
+    }
+
+    const batch = this.buffer.splice(0, this.buffer.length)
+    const queryEvents = batch.filter((event) => event.queryId != null)
+    if (queryEvents.length === 1) {
+      queryEvents[0]!.queryId = null
+    }
+
+    try {
+      if (this.service.write) {
+        await this.service.write(batch)
+        return
+      }
+
+      for (const event of batch) {
+        await this.service.audit(event)
+      }
+    } catch (error) {
+      ;(this.wire as any).logger?.warn?.(
+        'best-effort audit flush failed',
+        error
+      )
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.flush()
+  }
+
+  private resolveEvent(event: AuditLogWriteInput): AuditEvent {
+    return {
+      functionId: this.wire.functionId,
+      wireType: this.wire.wireType,
+      wireId: this.wire.wireId,
+      traceId: this.wire.traceId,
+      actor: event.actor ?? resolveAuditActorFromWire(this.wire),
+      ...event,
+      occurredAt: new Date().toISOString(),
+    }
+  }
+}
+
+export const resolveAuditConfig = (
+  config?: AuditConfig
+): ResolvedAuditConfig | undefined => {
+  if (config === true) {
+    return { durability: 'best-effort' }
+  }
+
+  if (!config) {
+    return undefined
+  }
+
+  return {
+    durability: config.durability ?? 'best-effort',
+  }
+}
+
+export const createInvocationAudit = (
+  service: AuditService,
+  wire: PikkuWire<any, any, any, CoreUserSession>
+): AuditLog => {
+  if (!wire.audit) {
+    return new DisabledInvocationAudit(wire)
+  }
+
+  return new InvocationAuditLog(wire.audit, service, wire)
+}
+
+export const resolveAuditActorFromWire = (
+  wire: PikkuWire<any, any, any, CoreUserSession>
+): AuditActor | undefined => {
+  const session = wire.session as CoreUserSession | undefined
+  const actor: AuditActor = {
+    userId: session?.userId,
+    orgId: session?.orgId,
+    pikkuUserId: wire.pikkuUserId,
+  }
+
+  if (!actor.userId && !actor.orgId && !actor.pikkuUserId) {
+    return undefined
+  }
+
+  return actor
+}

package/src/services/content-service.ts

@@ -25,6 +25,7 @@ export interface GetUploadURLArgs<TBucket extends string = string> {
   fileKey: string
   contentType: string
   size?: number
+  visibility?: 'private' | 'public'
 }
 
 /**

package/src/services/email-service.ts

@@ -0,0 +1,46 @@
+export interface EmailTemplateReference {
+  name: string
+  locale?: string
+  data?: Record<string, unknown>
+}
+
+export interface BaseSendEmailInput {
+  to: string | string[]
+  from?: string
+  cc?: string | string[]
+  bcc?: string | string[]
+  replyTo?: string | string[]
+  headers?: Record<string, string>
+  subject?: string
+}
+
+export interface SendTextEmailInput extends BaseSendEmailInput {
+  text: string
+  html?: never
+  template?: never
+}
+
+export interface SendHTMLEmailInput extends BaseSendEmailInput {
+  html: string
+  text?: string
+  template?: never
+}
+
+export interface SendTemplateEmailInput extends BaseSendEmailInput {
+  template: EmailTemplateReference
+  html?: never
+  text?: never
+}
+
+export type SendEmailInput =
+  | SendTextEmailInput
+  | SendHTMLEmailInput
+  | SendTemplateEmailInput
+
+export interface SendEmailResult {
+  messageId?: string
+}
+
+export interface EmailService {
+  send(input: SendEmailInput): Promise<SendEmailResult>
+}