@pikku/core 0.12.23 → 0.12.25

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>
+}

package/src/services/gopass-secrets.ts

@@ -6,10 +6,6 @@ import type { SecretService } from './secret-service.js'
  * Requires gopass to be installed and configured on the system.
  */
 export class GopassSecretService implements SecretService {
-  /**
-   * Creates an instance of GopassSecretService.
-   * @param prefix - Optional prefix for all secret keys (e.g., 'pikku/' will look up 'pikku/mykey' for key 'mykey')
-   */
   constructor(private prefix: string = '') {}
 
   private getFullKey(key: string): string {
@@ -19,39 +15,22 @@ export class GopassSecretService implements SecretService {
     return this.prefix ? `${this.prefix}${key}` : key
   }
 
-  /**
-   * Retrieves a secret by key and parses it as JSON.
-   * @param key - The key of the secret to retrieve.
-   * @returns A promise that resolves to the parsed secret value.
-   * @throws {Error} If the secret is not found or gopass fails.
-   */
-  public async getSecretJSON<R>(key: string): Promise<R> {
-    const value = await this.getSecret(key)
-    return JSON.parse(value)
-  }
-
-  /**
-   * Retrieves a secret by key as a string.
-   * @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 or gopass fails.
-   */
-  public async getSecret(key: string): Promise<string> {
+  public async getSecret<T = string>(key: string): Promise<T> {
     const fullKey = this.getFullKey(key)
     try {
-      return execFileSync('gopass', ['show', '-o', fullKey], {
+      const raw = execFileSync('gopass', ['show', '-o', fullKey], {
         encoding: 'utf8',
       }).trim()
+      try {
+        return JSON.parse(raw) as T
+      } catch {
+        return raw as unknown as T
+      }
     } catch (error: any) {
       throw new Error(`Secret Not Found: ${key}`, { cause: error })
     }
   }
 
-  /**
-   * Checks if a secret exists without throwing.
-   * @param key - The key of the secret to check.
-   * @returns A promise that resolves to true if the secret exists.
-   */
   public async hasSecret(key: string): Promise<boolean> {
     const fullKey = this.getFullKey(key)
     try {
@@ -62,19 +41,13 @@ export class GopassSecretService implements SecretService {
     }
   }
 
-  /**
-   * Stores a JSON value as a secret in gopass.
-   * @param key - The key to store the secret under.
-   * @param value - The JSON value to store.
-   * @returns A promise that resolves when the secret is stored.
-   */
-  public async setSecretJSON(key: string, value: unknown): Promise<void> {
+  public async setSecret(key: string, value: unknown): Promise<void> {
     const fullKey = this.getFullKey(key)
-    const jsonValue = JSON.stringify(value)
+    const encoded = typeof value === 'string' ? value : JSON.stringify(value)
     try {
       execFileSync('gopass', ['insert', '-f', fullKey], {
         encoding: 'utf8',
-        input: jsonValue,
+        input: encoded,
         stdio: ['pipe', 'pipe', 'pipe'],
       })
     } catch (error: any) {
@@ -82,11 +55,6 @@ export class GopassSecretService implements SecretService {
     }
   }
 
-  /**
-   * Deletes a secret from gopass.
-   * @param key - The key of the secret to delete.
-   * @returns A promise that resolves when the secret is deleted.
-   */
   public async deleteSecret(key: string): Promise<void> {
     const fullKey = this.getFullKey(key)
     try {

package/src/services/index.ts

@@ -17,6 +17,7 @@ export {
 } from './credential-wire-service.js'
 export { TypedVariablesService } from './typed-variables-service.js'
 export { LocalSecretService } from './local-secrets.js'
+export { LocalEmailService } from './local-email-service.js'
 export { LocalCredentialService } from './local-credential-service.js'
 export { LocalVariablesService } from './local-variables.js'
 export { ConsoleLogger, JsonConsoleLogger } from './logger-console.js'
@@ -36,6 +37,15 @@ export type {
   CopyFileArgs,
 } from './content-service.js'
 export type { JWTService } from './jwt-service.js'
+export type {
+  EmailService,
+  EmailTemplateReference,
+  SendEmailInput,
+  SendEmailResult,
+  SendHTMLEmailInput,
+  SendTemplateEmailInput,
+  SendTextEmailInput,
+} from './email-service.js'
 export type { Logger } from './logger.js'
 export type { SecretService } from './secret-service.js'
 export type { VariablesService } from './variables-service.js'
@@ -78,6 +88,25 @@ export type {
 export type { VariableStatus, VariableMeta } from './typed-variables-service.js'
 export type { MetaService } from './meta-service.js'
 export type { SessionStore } from './session-store.js'
+export {
+  NoopAuditService,
+  createInvocationAudit,
+  resolveAuditActorFromWire,
+  resolveAuditConfig,
+} from './audit-service.js'
+export type {
+  AuditActor,
+  AuditConfig,
+  AuditDurability,
+  AuditEvent,
+  AuditEventBatch,
+  AuditLog,
+  AuditLogWriteInput,
+  AuditOutcome,
+  AuditService,
+  AuditSource,
+  ResolvedAuditConfig,
+} from './audit-service.js'
 export { InMemorySessionStore } from './in-memory-session-store.js'
 export type {
   MCPMeta,
@@ -96,4 +125,8 @@ export type {
   PermissionMeta,
   AgentsMeta,
   AgentMeta,
+  EmailsMeta,
+  EmailTemplateMeta,
+  EmailTemplateLocaleMeta,
+  EmailTemplateAssets,
 } from './meta-service.js'

package/src/services/local-content.ts

@@ -106,6 +106,7 @@ export class LocalContent implements ContentService {
   }
 
   public async getUploadURL(args: GetUploadURLArgs): Promise<UploadURLResult> {
+    void args.visibility
     const fullKey = this.joinKey(args.bucket, args.fileKey)
     this.logger.debug(`Going to upload with key: ${fullKey}`)
     return {

package/src/services/local-email-service.test.ts

@@ -0,0 +1,108 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+
+import { LocalEmailService } from './local-email-service.js'
+
+test('LocalEmailService logs sent email metadata as JSON', async () => {
+  const service = new LocalEmailService()
+  const writes: string[] = []
+  const originalInfo = console.info
+  console.info = (value?: unknown) => {
+    writes.push(String(value))
+  }
+
+  try {
+    await service.send({
+      to: 'user@example.com',
+      from: 'hello@example.com',
+      subject: 'Welcome',
+      template: {
+        name: 'welcome',
+        locale: 'en',
+        data: { userName: 'Yasser' },
+      },
+    })
+  } finally {
+    console.info = originalInfo
+  }
+
+  assert.equal(writes.length, 1)
+  const payload = JSON.parse(writes[0])
+  assert.equal(payload.type, 'email')
+  assert.equal(payload.message, 'this email was sent')
+  assert.equal(payload.to, 'user@example.com')
+  assert.equal(payload.from, 'hello@example.com')
+  assert.equal(payload.subject, 'Welcome')
+  assert.deepEqual(payload.template, {
+    name: 'welcome',
+    locale: 'en',
+    data: { userName: 'Yasser' },
+  })
+})
+
+test('LocalEmailService logs htmlLength and textLength for HTML email', async () => {
+  const service = new LocalEmailService()
+  const writes: string[] = []
+  const originalInfo = console.info
+  console.info = (value?: unknown) => {
+    writes.push(String(value))
+  }
+
+  try {
+    await service.send({
+      to: 'user@example.com',
+      html: '<p>Hello</p>',
+      text: 'Hello',
+    })
+  } finally {
+    console.info = originalInfo
+  }
+
+  const payload = JSON.parse(writes[0])
+  assert.equal(payload.htmlLength, '<p>Hello</p>'.length)
+  assert.equal(payload.textLength, 'Hello'.length)
+})
+
+test('LocalEmailService logs textLength only for plain text email', async () => {
+  const service = new LocalEmailService()
+  const writes: string[] = []
+  const originalInfo = console.info
+  console.info = (value?: unknown) => {
+    writes.push(String(value))
+  }
+
+  try {
+    await service.send({
+      to: 'user@example.com',
+      text: 'Plain text body',
+    })
+  } finally {
+    console.info = originalInfo
+  }
+
+  const payload = JSON.parse(writes[0])
+  assert.equal(payload.textLength, 'Plain text body'.length)
+  assert.equal(payload.htmlLength, undefined)
+})
+
+test('LocalEmailService logs null textLength for HTML email without plain text', async () => {
+  const service = new LocalEmailService()
+  const writes: string[] = []
+  const originalInfo = console.info
+  console.info = (value?: unknown) => {
+    writes.push(String(value))
+  }
+
+  try {
+    await service.send({
+      to: 'user@example.com',
+      html: '<p>Hello</p>',
+    })
+  } finally {
+    console.info = originalInfo
+  }
+
+  const payload = JSON.parse(writes[0])
+  assert.equal(payload.htmlLength, '<p>Hello</p>'.length)
+  assert.equal(payload.textLength, null)
+})

package/src/services/local-email-service.ts

@@ -0,0 +1,30 @@
+import type { EmailService, SendEmailInput, SendEmailResult } from './email-service.js'
+
+export class LocalEmailService implements EmailService {
+  async send(input: SendEmailInput): Promise<SendEmailResult> {
+    const payload: Record<string, unknown> = {
+      type: 'email',
+      message: 'this email was sent',
+      to: input.to,
+      from: input.from ?? null,
+      cc: input.cc ?? null,
+      bcc: input.bcc ?? null,
+      replyTo: input.replyTo ?? null,
+      subject: input.subject ?? null,
+    }
+
+    if ('template' in input && input.template) {
+      payload.template = input.template
+    }
+    if ('html' in input && typeof input.html === 'string') {
+      payload.htmlLength = input.html.length
+      payload.textLength = input.text?.length ?? null
+    }
+    if ('text' in input && typeof input.text === 'string') {
+      payload.textLength = input.text.length
+    }
+
+    console.info(JSON.stringify(payload))
+    return {}
+  }
+}

package/src/services/local-secrets.test.ts

@@ -6,9 +6,9 @@ import { LocalVariablesService } from './local-variables.js'
 describe('LocalSecretService', () => {
   test('should get secret from local storage', async () => {
     const service = new LocalSecretService()
-    await service.setSecretJSON('MY_KEY', { token: 'abc' })
+    await service.setSecret('MY_KEY', { token: 'abc' })
     const result = await service.getSecret('MY_KEY')
-    assert.strictEqual(result, '{"token":"abc"}')
+    assert.deepStrictEqual(result, { token: 'abc' })
   })
 
   test('should get secret from environment variables', async () => {
@@ -28,22 +28,22 @@ describe('LocalSecretService', () => {
 
   test('should get JSON secret from local storage', async () => {
     const service = new LocalSecretService()
-    await service.setSecretJSON('JSON_KEY', { data: 42 })
-    const result = await service.getSecretJSON('JSON_KEY')
+    await service.setSecret('JSON_KEY', { data: 42 })
+    const result = await service.getSecret('JSON_KEY')
     assert.deepStrictEqual(result, { data: 42 })
   })
 
   test('should get JSON secret from environment variables', async () => {
     const vars = new LocalVariablesService({ CONFIG: '{"port":3000}' })
     const service = new LocalSecretService(vars)
-    const result = await service.getSecretJSON('CONFIG')
+    const result = await service.getSecret('CONFIG')
     assert.deepStrictEqual(result, { port: 3000 })
   })
 
   test('should throw when JSON secret not found', async () => {
     const vars = new LocalVariablesService({})
     const service = new LocalSecretService(vars)
-    await assert.rejects(() => service.getSecretJSON('MISSING'), {
+    await assert.rejects(() => service.getSecret('MISSING'), {
       message: 'Requested secret not found',
     })
   })
@@ -51,15 +51,15 @@ describe('LocalSecretService', () => {
   test('should prefer local storage over env variables', async () => {
     const vars = new LocalVariablesService({ KEY: 'env-value' })
     const service = new LocalSecretService(vars)
-    await service.setSecretJSON('KEY', 'local-value')
+    await service.setSecret('KEY', 'local-value')
     const result = await service.getSecret('KEY')
-    assert.strictEqual(result, '"local-value"')
+    assert.strictEqual(result, 'local-value')
   })
 
   test('should check hasSecret in local storage', async () => {
     const vars = new LocalVariablesService({})
     const service = new LocalSecretService(vars)
-    await service.setSecretJSON('EXISTS', 'yes')
+    await service.setSecret('EXISTS', 'yes')
     assert.strictEqual(await service.hasSecret('EXISTS'), true)
     assert.strictEqual(await service.hasSecret('NOPE'), false)
   })
@@ -72,7 +72,7 @@ describe('LocalSecretService', () => {
 
   test('should delete secret from local storage', async () => {
     const service = new LocalSecretService()
-    await service.setSecretJSON('DEL_KEY', 'value')
+    await service.setSecret('DEL_KEY', 'value')
     assert.strictEqual(await service.hasSecret('DEL_KEY'), true)
     await service.deleteSecret('DEL_KEY')
     assert.strictEqual(await service.hasSecret('DEL_KEY'), false)

package/src/services/local-secrets.ts

@@ -9,72 +9,38 @@ import type { VariablesService } from './variables-service.js'
 export class LocalSecretService implements SecretService {
   private localSecrets: Map<string, string> = new Map()
 
-  /**
-   * Creates an instance of LocalSecretService.
-   */
+  private parseSecret<T>(raw: string): T {
+    try {
+      return JSON.parse(raw) as T
+    } catch {
+      return raw as unknown as T
+    }
+  }
+
   constructor(
     private variables: VariablesService = new LocalVariablesService()
   ) {}
 
-  /**
-   * Retrieves a secret by key.
-   * Checks local storage first, then falls back to environment variables.
-   * @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.
-   */
-  public async getSecretJSON<R>(key: string): Promise<R> {
-    // Check local storage first
-    const localValue = this.localSecrets.get(key)
-    if (localValue) {
-      return JSON.parse(localValue)
-    }
-
-    // Fall back to environment variables
-    const value = await this.variables.get(key)
-    if (value) {
-      return JSON.parse(value)
-    }
-    throw new Error('Requested secret not found')
-  }
-
-  /**
-   * Retrieves a secret by key.
-   * Checks local storage first, then falls back to environment variables.
-   * @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.
-   */
-  public async getSecret(key: string): Promise<string> {
-    // Check local storage first
+  public async getSecret<T = string>(key: string): Promise<T> {
     const localValue = this.localSecrets.get(key)
     if (localValue) {
-      return localValue
+      return this.parseSecret<T>(localValue)
     }
 
-    // Fall back to environment variables
     const value = await this.variables.get(key)
     if (value) {
-      return value
+      return this.parseSecret<T>(value)
     }
     throw new Error('Requested secret not found')
   }
 
-  /**
-   * Stores a JSON value as a secret in local storage.
-   * @param key - The key to store the secret under.
-   * @param value - The JSON value to store.
-   * @returns A promise that resolves when the secret is stored.
-   */
-  public async setSecretJSON(key: string, value: unknown): Promise<void> {
-    this.localSecrets.set(key, JSON.stringify(value))
+  public async setSecret(key: string, value: unknown): Promise<void> {
+    this.localSecrets.set(
+      key,
+      typeof value === 'string' ? value : JSON.stringify(value)
+    )
   }
 
-  /**
-   * Checks if a secret exists without throwing.
-   * @param key - The key of the secret to check.
-   * @returns A promise that resolves to true if the secret exists.
-   */
   public async hasSecret(key: string): Promise<boolean> {
     if (this.localSecrets.has(key)) {
       return true
@@ -83,11 +49,6 @@ export class LocalSecretService implements SecretService {
     return value !== undefined && value !== null && value !== ''
   }
 
-  /**
-   * Deletes a secret from local storage.
-   * @param key - The key of the secret to delete.
-   * @returns A promise that resolves when the secret is deleted.
-   */
   public async deleteSecret(key: string): Promise<void> {
     this.localSecrets.delete(key)
   }

package/src/services/local-variables.test.ts

@@ -39,19 +39,19 @@ describe('LocalVariablesService', () => {
 
   test('should get JSON variable', () => {
     const service = new LocalVariablesService({ DATA: '{"key":"val"}' })
-    const result = service.getJSON('DATA')
+    const result = service.get('DATA')
     assert.deepStrictEqual(result, { key: 'val' })
   })
 
   test('should return undefined for missing JSON variable', () => {
     const service = new LocalVariablesService({})
-    assert.strictEqual(service.getJSON('MISSING'), undefined)
+    assert.strictEqual(service.get('MISSING'), undefined)
   })
 
   test('should set JSON variable', () => {
     const service = new LocalVariablesService({})
-    service.setJSON('DATA', { key: 'val' })
-    assert.strictEqual(service.get('DATA'), '{"key":"val"}')
+    service.set('DATA', { key: 'val' })
+    assert.deepStrictEqual(service.get('DATA'), { key: 'val' })
   })
 
   test('should handle has with undefined value', () => {

package/src/services/local-variables.ts

@@ -5,28 +5,23 @@ export class LocalVariablesService implements VariablesService {
     private variables: Record<string, string | undefined> = process.env
   ) {}
 
-  public getAll():
-    | Promise<Record<string, string | undefined>>
-    | Record<string, string | undefined> {
+  public getAll(): Record<string, string | undefined> {
     return this.variables || {}
   }
 
-  public get(name: string): Promise<string | undefined> | string | undefined {
-    return this.variables[name]
+  public get<T = string>(name: string): T | undefined {
+    const raw = this.variables[name]
+    if (raw === undefined) return undefined
+    try {
+      return JSON.parse(raw) as T
+    } catch {
+      return raw as unknown as T
+    }
   }
 
-  public getJSON<T = unknown>(name: string): T | undefined {
-    const value = this.variables[name]
-    if (value === undefined) return undefined
-    return JSON.parse(value)
-  }
-
-  public set(name: string, value: string): void {
-    this.variables[name] = value
-  }
-
-  public setJSON(name: string, value: unknown): void {
-    this.variables[name] = JSON.stringify(value)
+  public set(name: string, value: unknown): void {
+    this.variables[name] =
+      typeof value === 'string' ? value : JSON.stringify(value)
   }
 
   public has(name: string): boolean {