@pikku/core 0.12.4 → 0.12.5

package/src/services/schema-service.ts

@@ -0,0 +1,33 @@
+/**
+ * Interface for a schema service that handles schema compilation, validation, and management.
+ */
+export interface SchemaService {
+  /**
+   * Compiles a schema with the provided name and value, making it available for use.
+   * @param {string} name - The unique name for the schema.
+   * @param {any} value - The schema definition or configuration to be compiled.
+   * @returns {Promise<void> | void} A promise if asynchronous, or void if synchronous.
+   */
+  compileSchema: (name: string, value: any) => Promise<void> | void
+
+  /**
+   * Validates data against a specified schema.
+   * @param {string} schema - The name of the schema to validate against.
+   * @param {any} data - The data to validate against the schema.
+   * @returns {Promise<void> | void} A promise if asynchronous, or void if synchronous.
+   */
+  validateSchema: (schema: string, data: any) => Promise<void> | void
+
+  /**
+   * Retrieves a set of all registered schema names.
+   * @returns {Set<string>} A set containing the names of all available schemas.
+   */
+  getSchemaNames: () => Set<string>
+
+  /**
+   * Retrieves the property keys from a compiled JSON schema.
+   * @param {string} schemaName - The name of the schema.
+   * @returns {string[]} An array of property keys, or empty array if schema not found.
+   */
+  getSchemaKeys: (schemaName: string) => string[]
+}

package/src/services/scoped-secret-service.test.ts

@@ -0,0 +1,74 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { ScopedSecretService } from './scoped-secret-service.js'
+
+const createMockSecrets = () => ({
+  getSecret: async (key: string) => `value-of-${key}`,
+  getSecretJSON: async (key: string) => ({ key }),
+  hasSecret: async () => true,
+  setSecretJSON: async () => {},
+  deleteSecret: async () => {},
+})
+
+describe('ScopedSecretService', () => {
+  test('should allow access to allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1', 'KEY2']))
+    const result = await scoped.getSecret('KEY1')
+    assert.strictEqual(result, 'value-of-KEY1')
+  })
+
+  test('should deny access to non-allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    await assert.rejects(() => scoped.getSecret('KEY2'), {
+      message: 'Access denied to secret key: KEY2',
+    })
+  })
+
+  test('should allow getSecretJSON for allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    const result = await scoped.getSecretJSON('KEY1')
+    assert.deepStrictEqual(result, { key: 'KEY1' })
+  })
+
+  test('should deny getSecretJSON for non-allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    await assert.rejects(() => scoped.getSecretJSON('FORBIDDEN'), {
+      message: 'Access denied to secret key: FORBIDDEN',
+    })
+  })
+
+  test('should allow hasSecret for allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    const result = await scoped.hasSecret('KEY1')
+    assert.strictEqual(result, true)
+  })
+
+  test('should deny hasSecret for non-allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    await assert.rejects(() => scoped.hasSecret('KEY2'), {
+      message: 'Access denied to secret key: KEY2',
+    })
+  })
+
+  test('should always throw on setSecretJSON', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    await assert.rejects(() => scoped.setSecretJSON('KEY1', 'val'), {
+      message: 'setSecretJSON is not allowed in scoped secret service',
+    })
+  })
+
+  test('should always throw on deleteSecret', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    await assert.rejects(() => scoped.deleteSecret('KEY1'), {
+      message: 'deleteSecret is not allowed in scoped secret service',
+    })
+  })
+})

package/src/services/scoped-secret-service.ts

@@ -0,0 +1,41 @@
+import type { SecretService } from './secret-service.js'
+
+/**
+ * A read-only wrapper around SecretService that restricts access
+ * to only a defined set of allowed secret keys.
+ */
+export class ScopedSecretService implements SecretService {
+  constructor(
+    private secrets: SecretService,
+    private allowedKeys: Set<string>
+  ) {}
+
+  private assertAllowed(key: string): void {
+    if (!this.allowedKeys.has(key)) {
+      throw new Error(`Access denied to secret key: ${key}`)
+    }
+  }
+
+  async getSecret(key: string): Promise<string> {
+    this.assertAllowed(key)
+    return this.secrets.getSecret(key)
+  }
+
+  async getSecretJSON<T = {}>(key: string): Promise<T> {
+    this.assertAllowed(key)
+    return this.secrets.getSecretJSON<T>(key)
+  }
+
+  async hasSecret(key: string): Promise<boolean> {
+    this.assertAllowed(key)
+    return this.secrets.hasSecret(key)
+  }
+
+  async setSecretJSON(_key: string, _value: unknown): Promise<void> {
+    throw new Error('setSecretJSON is not allowed in scoped secret service')
+  }
+
+  async deleteSecret(_key: string): Promise<void> {
+    throw new Error('deleteSecret is not allowed in scoped secret service')
+  }
+}

package/src/services/secret-service.ts

@@ -0,0 +1,38 @@
+/**
+ * Interface for retrieving and managing secrets.
+ */
+export interface SecretService {
+  /**
+   * 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 If the secret is not found.
+   */
+  getSecretJSON<Return = {}>(key: string): Promise<Return>
+  /**
+   * 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 If the secret is not found.
+   */
+  getSecret(key: string): Promise<string>
+  /**
+   * 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, false otherwise.
+   */
+  hasSecret(key: string): Promise<boolean>
+  /**
+   * Stores a JSON value as a secret.
+   * @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.
+   */
+  setSecretJSON(key: string, value: unknown): Promise<void>
+  /**
+   * Deletes a secret by key.
+   * @param key - The key of the secret to delete.
+   * @returns A promise that resolves when the secret is deleted.
+   */
+  deleteSecret(key: string): Promise<void>
+}

package/src/services/trigger-service.ts

@@ -0,0 +1,17 @@
+/**
+ * Abstract TriggerService interface.
+ *
+ * Implementations manage trigger subscriptions — listening to external events
+ * and dispatching to RPC targets or workflow starts.
+ */
+export interface TriggerService {
+  /**
+   * Start all triggers
+   */
+  start(): Promise<void>
+
+  /**
+   * Stop all triggers
+   */
+  stop(): Promise<void>
+}

package/src/services/typed-secret-service.test.ts

@@ -0,0 +1,93 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { TypedSecretService } from './typed-secret-service.js'
+
+const createMockSecrets = (store: Map<string, string> = new Map()) => ({
+  getSecret: async (key: string) => {
+    const val = store.get(key)
+    if (!val) throw new Error(`Not found: ${key}`)
+    return val
+  },
+  getSecretJSON: async (key: string) => {
+    const val = store.get(key)
+    if (!val) throw new Error(`Not found: ${key}`)
+    return JSON.parse(val)
+  },
+  hasSecret: async (key: string) => store.has(key),
+  setSecretJSON: async (key: string, value: unknown) => {
+    store.set(key, JSON.stringify(value))
+  },
+  deleteSecret: async (key: string) => {
+    store.delete(key)
+  },
+})
+
+describe('TypedSecretService', () => {
+  test('should delegate getSecret to underlying service', async () => {
+    const store = new Map([['API_KEY', 'sk-123']])
+    const service = new TypedSecretService(createMockSecrets(store), {})
+    const result = await service.getSecret('API_KEY')
+    assert.strictEqual(result, 'sk-123')
+  })
+
+  test('should delegate getSecretJSON to underlying service', async () => {
+    const store = new Map([['CONFIG', '{"port":3000}']])
+    const service = new TypedSecretService(createMockSecrets(store), {})
+    const result = await service.getSecretJSON('CONFIG')
+    assert.deepStrictEqual(result, { port: 3000 })
+  })
+
+  test('should delegate hasSecret to underlying service', async () => {
+    const store = new Map([['EXISTS', 'val']])
+    const service = new TypedSecretService(createMockSecrets(store), {})
+    assert.strictEqual(await service.hasSecret('EXISTS'), true)
+    assert.strictEqual(await service.hasSecret('MISSING'), false)
+  })
+
+  test('should delegate setSecretJSON to underlying service', async () => {
+    const store = new Map<string, string>()
+    const service = new TypedSecretService(createMockSecrets(store), {})
+    await service.setSecretJSON('NEW_KEY', { data: 'val' })
+    assert.strictEqual(store.get('NEW_KEY'), '{"data":"val"}')
+  })
+
+  test('should delegate deleteSecret to underlying service', async () => {
+    const store = new Map([['KEY', 'val']])
+    const service = new TypedSecretService(createMockSecrets(store), {})
+    await service.deleteSecret('KEY')
+    assert.strictEqual(store.has('KEY'), false)
+  })
+
+  test('should get all status for credentials', async () => {
+    const store = new Map([['STRIPE_KEY', 'sk-123']])
+    const meta = {
+      STRIPE_KEY: { name: 'stripe', displayName: 'Stripe' },
+      GITHUB_TOKEN: {
+        name: 'github',
+        displayName: 'GitHub',
+        oauth2: { tokenSecretId: 'GH_TOKEN' },
+      },
+    }
+    const service = new TypedSecretService(createMockSecrets(store), meta)
+    const status = await service.getAllStatus()
+    assert.strictEqual(status.length, 2)
+    const stripeStatus = status.find((s) => s.secretId === 'STRIPE_KEY')!
+    assert.strictEqual(stripeStatus.isConfigured, true)
+    assert.strictEqual(stripeStatus.displayName, 'Stripe')
+    const ghStatus = status.find((s) => s.secretId === 'GITHUB_TOKEN')!
+    assert.strictEqual(ghStatus.isConfigured, false)
+    assert.deepStrictEqual(ghStatus.oauth2, { tokenSecretId: 'GH_TOKEN' })
+  })
+
+  test('should get missing credentials', async () => {
+    const store = new Map([['STRIPE_KEY', 'sk-123']])
+    const meta = {
+      STRIPE_KEY: { name: 'stripe', displayName: 'Stripe' },
+      GITHUB_TOKEN: { name: 'github', displayName: 'GitHub' },
+    }
+    const service = new TypedSecretService(createMockSecrets(store), meta)
+    const missing = await service.getMissing()
+    assert.strictEqual(missing.length, 1)
+    assert.strictEqual(missing[0].secretId, 'GITHUB_TOKEN')
+  })
+})

package/src/services/typed-secret-service.ts

@@ -0,0 +1,70 @@
+import type { SecretService } from './secret-service.js'
+
+export interface CredentialStatus {
+  secretId: string
+  name: string
+  displayName: string
+  isConfigured: boolean
+  oauth2?: { tokenSecretId: string }
+}
+
+export type CredentialMeta = {
+  name: string
+  displayName: string
+  oauth2?: { tokenSecretId: string }
+}
+
+export class TypedSecretService<TMap = Record<string, unknown>>
+  implements SecretService
+{
+  constructor(
+    private secrets: SecretService,
+    private credentialsMeta: Record<string, CredentialMeta>
+  ) {}
+
+  async getSecretJSON<K extends keyof TMap & string>(key: K): Promise<TMap[K]>
+  async getSecretJSON<T = unknown>(key: string): Promise<T>
+  async getSecretJSON(key: string): Promise<unknown> {
+    return this.secrets.getSecretJSON(key)
+  }
+
+  async getSecret(key: string): Promise<string> {
+    return this.secrets.getSecret(key)
+  }
+
+  async hasSecret(key: string): Promise<boolean> {
+    return this.secrets.hasSecret(key)
+  }
+
+  async setSecretJSON<K extends string>(
+    key: K,
+    value: K extends keyof TMap ? TMap[K] : unknown
+  ): Promise<void> {
+    return this.secrets.setSecretJSON(key, value)
+  }
+
+  async deleteSecret(key: string): Promise<void> {
+    return this.secrets.deleteSecret(key)
+  }
+
+  async getAllStatus(): Promise<CredentialStatus[]> {
+    const results: CredentialStatus[] = []
+
+    for (const [secretId, meta] of Object.entries(this.credentialsMeta)) {
+      results.push({
+        secretId,
+        name: meta.name,
+        displayName: meta.displayName,
+        isConfigured: await this.secrets.hasSecret(secretId),
+        oauth2: meta.oauth2,
+      })
+    }
+
+    return results
+  }
+
+  async getMissing(): Promise<CredentialStatus[]> {
+    const all = await this.getAllStatus()
+    return all.filter((c) => !c.isConfigured)
+  }
+}

package/src/services/typed-variables-service.test.ts

@@ -0,0 +1,73 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { TypedVariablesService } from './typed-variables-service.js'
+import { LocalVariablesService } from './local-variables.js'
+
+describe('TypedVariablesService', () => {
+  const createService = (vars: Record<string, string | undefined> = {}) => {
+    const underlying = new LocalVariablesService(vars)
+    const meta = {
+      DB_URL: { name: 'DB_URL', displayName: 'Database URL' },
+      API_KEY: { name: 'API_KEY', displayName: 'API Key' },
+    }
+    return new TypedVariablesService(underlying, meta)
+  }
+
+  test('should delegate get to underlying service', () => {
+    const service = createService({ DB_URL: 'postgres://...' })
+    assert.strictEqual(service.get('DB_URL'), 'postgres://...')
+  })
+
+  test('should delegate set to underlying service', () => {
+    const service = createService()
+    service.set('DB_URL', 'new-value')
+    assert.strictEqual(service.get('DB_URL'), 'new-value')
+  })
+
+  test('should delegate has to underlying service', () => {
+    const service = createService({ DB_URL: 'val' })
+    assert.strictEqual(service.has('DB_URL'), true)
+    assert.strictEqual(service.has('MISSING'), false)
+  })
+
+  test('should delegate delete to underlying service', () => {
+    const service = createService({ DB_URL: 'val' })
+    service.delete('DB_URL')
+    assert.strictEqual(service.has('DB_URL'), false)
+  })
+
+  test('should delegate getJSON to underlying service', () => {
+    const service = createService({ DATA: '{"key":"val"}' })
+    assert.deepStrictEqual(service.getJSON('DATA'), { key: 'val' })
+  })
+
+  test('should delegate setJSON to underlying service', () => {
+    const service = createService()
+    service.setJSON('DATA', { key: 'val' })
+    assert.strictEqual(service.get('DATA'), '{"key":"val"}')
+  })
+
+  test('should get all status for configured variables', async () => {
+    const service = createService({ DB_URL: 'postgres://...' })
+    const status = await service.getAllStatus()
+    assert.strictEqual(status.length, 2)
+    const dbStatus = status.find((s) => s.variableId === 'DB_URL')!
+    assert.strictEqual(dbStatus.isConfigured, true)
+    assert.strictEqual(dbStatus.displayName, 'Database URL')
+    const apiStatus = status.find((s) => s.variableId === 'API_KEY')!
+    assert.strictEqual(apiStatus.isConfigured, false)
+  })
+
+  test('should get missing variables', async () => {
+    const service = createService({ DB_URL: 'val' })
+    const missing = await service.getMissing()
+    assert.strictEqual(missing.length, 1)
+    assert.strictEqual(missing[0].variableId, 'API_KEY')
+  })
+
+  test('should return empty missing when all configured', async () => {
+    const service = createService({ DB_URL: 'val', API_KEY: 'key' })
+    const missing = await service.getMissing()
+    assert.strictEqual(missing.length, 0)
+  })
+})

package/src/services/typed-variables-service.ts

@@ -0,0 +1,81 @@
+import type { VariablesService } from './variables-service.js'
+
+export interface VariableStatus {
+  variableId: string
+  name: string
+  displayName: string
+  isConfigured: boolean
+}
+
+export type VariableMeta = {
+  name: string
+  displayName: string
+}
+
+export class TypedVariablesService<TMap = Record<string, unknown>>
+  implements VariablesService
+{
+  constructor(
+    private variables: VariablesService,
+    private variablesMeta: Record<string, VariableMeta>
+  ) {}
+
+  get(
+    name: keyof TMap & string
+  ): Promise<string | undefined> | string | undefined
+  get(name: string): Promise<string | undefined> | string | undefined
+  get(name: string): Promise<string | undefined> | string | undefined {
+    return this.variables.get(name)
+  }
+
+  getJSON<K extends keyof TMap & string>(
+    name: K
+  ): Promise<TMap[K] | undefined> | TMap[K] | undefined
+  getJSON<T = unknown>(name: string): Promise<T | undefined> | T | undefined
+  getJSON(name: string): Promise<unknown> | unknown {
+    return this.variables.getJSON(name)
+  }
+
+  getAll():
+    | Promise<Record<string, string | undefined>>
+    | Record<string, string | undefined> {
+    return this.variables.getAll()
+  }
+
+  set(name: string, value: string): Promise<void> | void {
+    return this.variables.set(name, value)
+  }
+
+  setJSON(name: string, value: unknown): Promise<void> | void {
+    return this.variables.setJSON(name, value)
+  }
+
+  has(name: string): Promise<boolean> | boolean {
+    return this.variables.has(name)
+  }
+
+  delete(name: string): Promise<void> | void {
+    return this.variables.delete(name)
+  }
+
+  async getAllStatus(): Promise<VariableStatus[]> {
+    const results: VariableStatus[] = []
+    const all = await this.variables.getAll()
+
+    for (const [variableId, meta] of Object.entries(this.variablesMeta)) {
+      results.push({
+        variableId,
+        name: meta.name,
+        displayName: meta.displayName,
+        isConfigured: all[variableId] !== undefined,
+      })
+    }
+
+    return results
+  }
+
+  async getMissing(): Promise<VariableStatus[]> {
+    const all = await this.getAllStatus()
+    return all.filter((v) => !v.isConfigured)
+  }
+}

package/src/services/user-session-service.test.ts

@@ -0,0 +1,113 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+  createFunctionSessionWireProps,
+} from './user-session-service.js'
+
+describe('PikkuSessionService', () => {
+  test('should set and get session', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    const session = service.get()
+    assert.deepStrictEqual(session, { userId: 'user-1' })
+  })
+
+  test('should return undefined when no session set', () => {
+    const service = new PikkuSessionService()
+    assert.strictEqual(service.get(), undefined)
+  })
+
+  test('should mark sessionChanged when set is called', () => {
+    const service = new PikkuSessionService()
+    assert.strictEqual(service.sessionChanged, false)
+    service.set({ userId: 'user-1' })
+    assert.strictEqual(service.sessionChanged, true)
+  })
+
+  test('should clear session', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    service.clear()
+    assert.strictEqual(service.get(), undefined)
+    assert.strictEqual(service.sessionChanged, true)
+  })
+
+  test('should freeze initial session', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    const frozen = service.freezeInitial()
+    assert.deepStrictEqual(frozen, { userId: 'user-1' })
+  })
+
+  test('should only freeze initial once', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    service.freezeInitial()
+    service.set({ userId: 'user-2' })
+    const frozen2 = service.freezeInitial()
+    assert.deepStrictEqual(frozen2, { userId: 'user-1' })
+  })
+
+  test('should throw when channelStore provided without channelId', () => {
+    assert.throws(() => new PikkuSessionService({} as any), {
+      message: 'Channel ID is required when using channel store',
+    })
+  })
+
+  test('should use channelStore when provided', async () => {
+    let storedSession: any
+    const store = {
+      setUserSession: (id: string, session: any) => {
+        storedSession = session
+      },
+      getChannelAndSession: (id: string) => ({ session: { userId: 'stored' } }),
+    }
+    const service = new PikkuSessionService(store as any, 'ch-1')
+    service.set({ userId: 'new' })
+    assert.deepStrictEqual(storedSession, { userId: 'new' })
+
+    const session = service.get()
+    assert.deepStrictEqual(session, { userId: 'stored' })
+  })
+})
+
+describe('createMiddlewareSessionWireProps', () => {
+  test('should return session wire props', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    const props = createMiddlewareSessionWireProps(service)
+    assert.ok('session' in props)
+    assert.ok('setSession' in props)
+    assert.ok('getSession' in props)
+    assert.ok('hasSessionChanged' in props)
+  })
+
+  test('setSession should call setInitial', () => {
+    const service = new PikkuSessionService()
+    const props = createMiddlewareSessionWireProps(service)
+    props.setSession({ userId: 'user-2' })
+    assert.deepStrictEqual(service.get(), { userId: 'user-2' })
+  })
+})
+
+describe('createFunctionSessionWireProps', () => {
+  test('should return function session wire props', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    const props = createFunctionSessionWireProps(service)
+    assert.ok('session' in props)
+    assert.ok('setSession' in props)
+    assert.ok('clearSession' in props)
+    assert.ok('getSession' in props)
+    assert.ok('hasSessionChanged' in props)
+  })
+
+  test('session should be frozen initial', () => {
+    const service = new PikkuSessionService()
+    service.setInitial({ userId: 'user-1' })
+    const props = createFunctionSessionWireProps(service)
+    assert.deepStrictEqual(props.session, { userId: 'user-1' })
+  })
+})