@pikku/core 0.12.16 → 0.12.18

package/dist/wirings/channel/serverless/serverless-channel-runner.js

@@ -34,7 +34,7 @@ export const runChannelConnect = async ({ channelId, channelObject, request, res
     if (request instanceof Request) {
         http = createHTTPWire(new PikkuFetchHTTPRequest(request), response);
     }
-    const userSession = new PikkuSessionService(channelStore, channelId);
+    const userSession = new PikkuSessionService(singletonServices.sessionStore);
     const { channelConfig, openingData, meta } = await openChannel({
         channelId,
         request,
@@ -77,6 +77,11 @@ export const runChannelConnect = async ({ channelId, channelObject, request, res
                 channelMiddlewareMeta: meta.channelMiddleware,
             });
         }
+        // Store the pikkuUserId mapping after auth middleware has run
+        const pikkuUserId = userSession.getPikkuUserId();
+        if (pikkuUserId) {
+            await channelStore.setPikkuUserId(channelId, pikkuUserId);
+        }
         http?.response?.status(101);
     }
     catch (e) {
@@ -98,21 +103,27 @@ export const runChannelDisconnect = async ({ channelId, channelStore, channelHan
     // there's nothing to disconnect, so we can return early.
     let channelData;
     try {
-        channelData = await channelStore.getChannelAndSession(channelId);
+        channelData = await channelStore.getChannel(channelId);
     }
     catch {
         singletonServices.logger.info(`Channel ${channelId} not found during disconnect - already cleaned up`);
         return;
     }
-    const { openingData, channelName, session } = channelData;
+    const { openingData, channelName, pikkuUserId } = channelData;
     const { channel, channelConfig, meta } = getVariablesForChannel({
         channelId,
         channelHandlerFactory,
         openingData,
         channelName,
     });
-    const userSession = new PikkuSessionService(channelStore, channelId);
-    userSession.setInitial(session);
+    const userSession = new PikkuSessionService(singletonServices.sessionStore);
+    if (pikkuUserId) {
+        userSession.setPikkuUserId(pikkuUserId);
+        const session = await singletonServices.sessionStore?.get(pikkuUserId);
+        if (session) {
+            userSession.setInitial(session);
+        }
+    }
     const wire = {
         channel,
         ...createMiddlewareSessionWireProps(userSession),
@@ -149,15 +160,21 @@ export const runChannelMessage = async ({ channelId, channelStore, channelHandle
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
     let wireServices;
-    const { openingData, channelName, session } = await channelStore.getChannelAndSession(channelId);
+    const { openingData, channelName, pikkuUserId } = await channelStore.getChannel(channelId);
     const { channel, channelHandler, channelConfig } = getVariablesForChannel({
         channelId,
         channelHandlerFactory,
         openingData,
         channelName,
     });
-    const userSession = new PikkuSessionService(channelStore, channelId);
-    userSession.setInitial(session);
+    const userSession = new PikkuSessionService(singletonServices.sessionStore);
+    if (pikkuUserId) {
+        userSession.setPikkuUserId(pikkuUserId);
+        const session = await singletonServices.sessionStore?.get(pikkuUserId);
+        if (session) {
+            userSession.setInitial(session);
+        }
+    }
     const wire = {
         channel,
         ...createMiddlewareSessionWireProps(userSession),

package/dist/wirings/cli/cli-runner.js

@@ -224,7 +224,7 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
         },
         state: 'open',
     };
-    const userSession = new PikkuSessionService();
+    const userSession = new PikkuSessionService(singletonServices.sessionStore);
     const wire = {
         cli: {
             program,

package/dist/wirings/http/http-runner.js

@@ -201,9 +201,9 @@ export const createHTTPWire = (request, response) => {
  * @throws Throws errors like MissingSessionError or ForbiddenError on validation failures.
  */
 const executeRoute = async (services, matchedRoute, http, options) => {
-    const userSession = new PikkuSessionService();
     const { params, route, meta } = matchedRoute;
     const { singletonServices, createWireServices, skipUserSession, requestId } = services;
+    const userSession = new PikkuSessionService(singletonServices.sessionStore);
     // Attach URL parameters to the request object
     http?.request?.setParams(params);
     // Validate request headers if schema is defined

package/dist/wirings/mcp/mcp-runner.js

@@ -103,7 +103,7 @@ async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncId, { mcp: mcp
             throw new NotFoundError(`MCP '${type}' PikkuFunction Mapping not found for '${name}'`);
         }
         singletonServices.logger.debug(`Running MCP ${type}: ${name}`);
-        const mcpSessionService = new PikkuSessionService();
+        const mcpSessionService = new PikkuSessionService(singletonServices.sessionStore);
         const wire = {
             mcp: mcpWire,
             ...createMiddlewareSessionWireProps(mcpSessionService),

package/dist/wirings/scheduler/scheduler-runner.js

@@ -41,7 +41,7 @@ export async function runScheduledTask({ name, session, traceId, }) {
         singletonServices.logger;
     const task = pikkuState(null, 'scheduler', 'tasks').get(name);
     const meta = pikkuState(null, 'scheduler', 'meta')[name];
-    const userSession = new PikkuSessionService();
+    const userSession = new PikkuSessionService(singletonServices.sessionStore);
     if (session) {
         userSession.set(session);
     }

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -425,7 +425,6 @@ export class PikkuWorkflowService {
             const wire = {
                 workflow: workflowWire,
                 pikkuUserId: run.wire?.pikkuUserId,
-                session: rpcService.wire?.session,
                 rpc: rpcService.wire?.rpc,
             };
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.16",
+  "version": "0.12.18",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",

package/src/function/function-runner.ts

@@ -26,15 +26,44 @@ import type {
 } from './functions.types.js'
 import { parseVersionedId } from '../version.js'
 import type { SessionService } from '../services/user-session-service.js'
-import { createFunctionSessionWireProps } from '../services/user-session-service.js'
+import {
+  PikkuSessionService,
+  createFunctionSessionWireProps,
+} from '../services/user-session-service.js'
 import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js'
 import {
   PikkuCredentialWireService,
   createWireServicesCredentialWireProps,
 } from '../services/credential-wire-service.js'
+import { defaultPikkuUserIdResolver } from '../services/pikku-user-id.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { closeWireServices } from '../utils.js'
 
+async function resolveSession(
+  wire: PikkuWire,
+  singletonServices: CoreSingletonServices,
+  sessionService?: SessionService<CoreUserSession>
+): Promise<void> {
+  const pikkuUserId = defaultPikkuUserIdResolver(wire)
+  if (pikkuUserId) {
+    wire.pikkuUserId = pikkuUserId
+    if (sessionService instanceof PikkuSessionService) {
+      sessionService.setPikkuUserId(pikkuUserId)
+    }
+  }
+
+  const { sessionStore } = singletonServices
+  if (!sessionStore || !pikkuUserId) return
+
+  if (!wire.session) {
+    const stored = await sessionStore.get(pikkuUserId)
+    if (stored) {
+      wire.session = stored
+      sessionService?.setInitial(stored)
+    }
+  }
+}
+
 /**
  * Get or create singleton services for an addon package.
  * Services are cached in pikkuState to avoid recreation on each call.
@@ -256,6 +285,12 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
   // Helper function to run permissions and execute the function
   const executeFunction = async () => {
+    await resolveSession(
+      resolvedWire,
+      resolvedSingletonServices,
+      sessionService
+    )
+
     if (sessionService) {
       resolvedWire.session = sessionService.freezeInitial()
       resolvedWire.setSession = (s: any) => sessionService.set(s)

package/src/function/index.ts

@@ -13,3 +13,10 @@ export type {
   CorePikkuAuthConfig,
   CorePikkuPermission,
 } from './functions.types.js'
+export type {
+  ListInput,
+  ListOutput,
+  Filter,
+  LeafFilter,
+  LeafValue,
+} from './list.types.js'

package/src/function/list.types.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Type-level tests for list-function primitives.
+ *
+ * No runtime assertions — the point is that valid shapes compile and
+ * invalid shapes fail with `@ts-expect-error`. The file is excluded
+ * from `yarn build` via tsconfig's `**∕*.test.ts` pattern.
+ */
+
+import type { ListInput, ListOutput, Filter } from './list.types.js'
+
+// -- ListInput ---------------------------------------------------------------
+
+type SessionFilter = {
+  status?: string[]
+  therapistId?: string
+  uploadedAt?: string
+}
+type SessionSort = 'user' | 'status' | 'uploaded_at'
+
+const _basic: ListInput<SessionFilter, SessionSort> = {
+  cursor: 'abc',
+  limit: 50,
+  sort: [
+    { column: 'uploaded_at', direction: 'desc' },
+    { column: 'status', direction: 'asc' },
+  ],
+  filter: { status: ['pending'] },
+  search: 'sarah',
+}
+void _basic
+
+const _empty: ListInput = {}
+void _empty
+
+// sort.column must be from the declared union
+// @ts-expect-error — 'created_at' is not in SessionSort
+const _badSort: ListInput<SessionFilter, SessionSort> = {
+  sort: [{ column: 'created_at', direction: 'asc' }],
+}
+void _badSort
+
+// sort.direction must be 'asc' or 'desc'
+// @ts-expect-error — 'descending' is not a valid direction
+const _badDirection: ListInput<SessionFilter, SessionSort> = {
+  sort: [{ column: 'user', direction: 'descending' }],
+}
+void _badDirection
+
+// -- ListOutput --------------------------------------------------------------
+
+interface Session {
+  id: string
+  user: string
+  status: string
+}
+
+const _output: ListOutput<Session> = {
+  rows: [{ id: '1', user: 'sarah', status: 'pending' }],
+  nextCursor: null,
+  totalCount: 42,
+}
+void _output
+
+// nextCursor is required (must be string or null, not undefined-only)
+// @ts-expect-error — missing nextCursor
+const _badOutput: ListOutput<Session> = {
+  rows: [],
+}
+void _badOutput
+
+// -- Filter: leaves ----------------------------------------------------------
+
+// Simple equality
+const _leafEq: Filter<SessionFilter> = { therapistId: 'kim' }
+void _leafEq
+
+// Array = IN shorthand
+const _leafIn: Filter<SessionFilter> = { status: ['pending', 'processed'] }
+void _leafIn
+
+// Operator object
+const _leafOp: Filter<SessionFilter> = {
+  uploadedAt: { gt: '2026-04-10', lte: '2026-04-17' },
+}
+void _leafOp
+
+// Null = IS NULL
+const _leafNull: Filter<SessionFilter> = { therapistId: null }
+void _leafNull
+
+// NOT on a value
+const _leafNot: Filter<SessionFilter> = { therapistId: { not: 'kim' } }
+void _leafNot
+
+// -- Filter: AND (array) -----------------------------------------------------
+
+const _and: Filter<SessionFilter> = [
+  { status: ['pending'] },
+  { therapistId: 'kim' },
+  { uploadedAt: { gt: '2026-04-10' } },
+]
+void _and
+
+// -- Filter: OR (object with arbitrary label keys) --------------------------
+
+const _or: Filter<SessionFilter> = {
+  viaKim: { therapistId: 'kim' },
+  viaPark: { therapistId: 'park' },
+}
+void _or
+
+// -- Filter: nested AND/OR ---------------------------------------------------
+
+const _nested: Filter<SessionFilter> = [
+  { status: ['pending'] },
+  {
+    kim: { therapistId: 'kim' },
+    park: { therapistId: 'park' },
+  },
+  { uploadedAt: { gt: '2026-04-10' } },
+]
+void _nested

package/src/function/list.types.ts

@@ -0,0 +1,121 @@
+/**
+ * List-function primitives.
+ *
+ * A "list function" is any Pikku function that returns a paginated
+ * collection. Adopting this shape unlocks a shared vocabulary across
+ * MCP tools, AI agents, typed RPC clients, and widget libraries — they
+ * all reason about cursor, filter, sort, and search uniformly.
+ *
+ * Under the hood, a list function is still a normal `pikkuFunc`. These
+ * types are purely structural constraints; no runtime behaviour change.
+ *
+ * @example
+ * ```ts
+ * import { pikkuFunc } from '#pikku'
+ * import type { ListInput, ListOutput } from '@pikku/core'
+ *
+ * export const listSessions = pikkuFunc<
+ *   ListInput<{ status?: SessionStatus[] }, 'user' | 'status' | 'uploaded_at'>,
+ *   ListOutput<Session>
+ * >({
+ *   func: async ({ kysely }, input) => {
+ *     // input.sort / input.filter / input.cursor / input.search are typed
+ *     return { rows, nextCursor, totalCount }
+ *   },
+ * })
+ * ```
+ */
+
+/**
+ * Shape every list function accepts as input.
+ *
+ * @template F - User-defined filter shape. Each key is a filterable field.
+ * @template S - String union of sortable column names.
+ */
+export interface ListInput<
+  F extends Record<string, unknown> = Record<string, never>,
+  S extends string = never,
+> {
+  /** Opaque cursor from the previous page's `nextCursor`. */
+  cursor?: string
+  /** Page size. Server may cap. */
+  limit?: number
+  /** Ordered sort criteria — first entry is primary. */
+  sort?: Array<{ column: S; direction: 'asc' | 'desc' }>
+  /** Structured filter tree. See {@link Filter}. */
+  filter?: Filter<F>
+  /** Unstructured text search across server-configured fields. */
+  search?: string
+}
+
+/**
+ * Shape every list function returns.
+ */
+export interface ListOutput<Row> {
+  rows: Row[]
+  /** Null when no more pages. */
+  nextCursor: string | null
+  /** Optional — backend may skip when expensive. */
+  totalCount?: number
+}
+
+/**
+ * Leaf predicate value on a single field.
+ *
+ * Operator keywords (`equals`, `not`, `in`, `notIn`, `gt`, `gte`, `lt`,
+ * `lte`, `contains`, `startsWith`, `endsWith`, `mode`) mirror Prisma's
+ * vocabulary for dev familiarity. These keys are reserved and cannot be
+ * used as user field names in a Filter's `F` type.
+ */
+export type LeafValue<T> =
+  | T
+  | null
+  | T[]
+  | {
+      equals?: T | null
+      not?: T | null | LeafValue<T>
+      in?: T[]
+      notIn?: T[]
+      gt?: T
+      gte?: T
+      lt?: T
+      lte?: T
+      contains?: string
+      startsWith?: string
+      endsWith?: string
+      mode?: 'sensitive' | 'insensitive'
+    }
+
+/**
+ * A single-key object keyed by a field name from F, value is a leaf
+ * predicate. Single-key so the runtime discriminator is unambiguous:
+ * multi-key objects are OR groups.
+ */
+export type LeafFilter<F extends Record<string, unknown>> = {
+  [K in keyof F]: { [Key in K]: LeafValue<F[K]> }
+}[keyof F]
+
+/**
+ * Recursive filter tree.
+ *
+ * - `Array<Filter<F>>` — AND of children.
+ * - `{ [label: string]: Filter<F> }` — OR of children. Keys are arbitrary
+ *   labels (unique strings), ignored at evaluation time.
+ * - `LeafFilter<F>` — single-key predicate on a declared field.
+ *
+ * @example "status = pending AND (therapist = kim OR therapist = park) AND uploaded_at > 2026-04-10"
+ * ```ts
+ * const filter: Filter<{ status: string; therapistId: string; uploadedAt: string }> = [
+ *   { status: 'pending' },
+ *   {
+ *     kim:  { therapistId: 'kim' },
+ *     park: { therapistId: 'park' },
+ *   },
+ *   { uploadedAt: { gt: '2026-04-10' } },
+ * ]
+ * ```
+ */
+export type Filter<F extends Record<string, unknown>> =
+  | LeafFilter<F>
+  | Filter<F>[]
+  | { [label: string]: Filter<F> }

package/src/index.ts

@@ -59,6 +59,13 @@ export {
   pikkuApprovalDescription,
 } from './function/functions.types.js'
 export { addFunction, getAllFunctionNames } from './function/index.js'
+export type {
+  ListInput,
+  ListOutput,
+  Filter,
+  LeafFilter,
+  LeafValue,
+} from './function/list.types.js'
 export { PikkuRequest } from './pikku-request.js'
 export {
   getRelativeTimeOffsetFromNow,

package/src/services/in-memory-session-store.test.ts

@@ -0,0 +1,58 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemorySessionStore } from './in-memory-session-store.js'
+
+describe('InMemorySessionStore', () => {
+  test('get returns undefined for unknown user', async () => {
+    const store = new InMemorySessionStore()
+    const result = await store.get('unknown')
+    assert.equal(result, undefined)
+  })
+
+  test('set and get round-trip', async () => {
+    const store = new InMemorySessionStore()
+    const session = { userId: 'user-1', organizationId: 'org-1' } as any
+    await store.set('user-1', session)
+
+    const result = await store.get('user-1')
+    assert.deepEqual(result, session)
+  })
+
+  test('set overwrites previous session', async () => {
+    const store = new InMemorySessionStore()
+    await store.set('user-1', { userId: 'user-1', role: 'admin' } as any)
+    await store.set('user-1', { userId: 'user-1', role: 'member' } as any)
+
+    const result = await store.get('user-1')
+    assert.deepEqual(result, { userId: 'user-1', role: 'member' })
+  })
+
+  test('clear removes session', async () => {
+    const store = new InMemorySessionStore()
+    await store.set('user-1', { userId: 'user-1' } as any)
+    assert.ok(await store.get('user-1'))
+
+    await store.clear('user-1')
+    const result = await store.get('user-1')
+    assert.equal(result, undefined)
+  })
+
+  test('clear is no-op for unknown user', async () => {
+    const store = new InMemorySessionStore()
+    await store.clear('nonexistent')
+  })
+
+  test('users are isolated', async () => {
+    const store = new InMemorySessionStore()
+    await store.set('user-a', { userId: 'a' } as any)
+    await store.set('user-b', { userId: 'b' } as any)
+
+    assert.deepEqual(await store.get('user-a'), { userId: 'a' })
+    assert.deepEqual(await store.get('user-b'), { userId: 'b' })
+
+    await store.clear('user-a')
+    assert.equal(await store.get('user-a'), undefined)
+    assert.deepEqual(await store.get('user-b'), { userId: 'b' })
+  })
+})

package/src/services/in-memory-session-store.ts

@@ -0,0 +1,21 @@
+import type { CoreUserSession } from '../types/core.types.js'
+import type { SessionStore } from './session-store.js'
+
+export class InMemorySessionStore<
+  UserSession extends CoreUserSession = CoreUserSession,
+> implements SessionStore<UserSession>
+{
+  private sessions = new Map<string, UserSession>()
+
+  async get(pikkuUserId: string): Promise<UserSession | undefined> {
+    return this.sessions.get(pikkuUserId)
+  }
+
+  async set(pikkuUserId: string, session: UserSession): Promise<void> {
+    this.sessions.set(pikkuUserId, session)
+  }
+
+  async clear(pikkuUserId: string): Promise<void> {
+    this.sessions.delete(pikkuUserId)
+  }
+}

package/src/services/index.ts

@@ -68,6 +68,8 @@ export type {
 } from './typed-credential-service.js'
 export type { VariableStatus, VariableMeta } from './typed-variables-service.js'
 export type { MetaService } from './meta-service.js'
+export type { SessionStore } from './session-store.js'
+export { InMemorySessionStore } from './in-memory-session-store.js'
 export type {
   MCPMeta,
   RPCMetaRecord,

package/src/services/session-store.ts

@@ -0,0 +1,9 @@
+import type { CoreUserSession } from '../types/core.types.js'
+
+export interface SessionStore<
+  UserSession extends CoreUserSession = CoreUserSession,
+> {
+  get(pikkuUserId: string): Promise<UserSession | undefined>
+  set(pikkuUserId: string, session: UserSession): Promise<void>
+  clear(pikkuUserId: string): Promise<void>
+}

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

@@ -19,17 +19,17 @@ describe('PikkuSessionService', () => {
     assert.strictEqual(service.get(), undefined)
   })
 
-  test('should mark sessionChanged when set is called', () => {
+  test('should mark sessionChanged when set is called', async () => {
     const service = new PikkuSessionService()
     assert.strictEqual(service.sessionChanged, false)
-    service.set({ userId: 'user-1' })
+    await service.set({ userId: 'user-1' })
     assert.strictEqual(service.sessionChanged, true)
   })
 
-  test('should clear session', () => {
+  test('should clear session', async () => {
     const service = new PikkuSessionService()
     service.setInitial({ userId: 'user-1' })
-    service.clear()
+    await service.clear()
     assert.strictEqual(service.get(), undefined)
     assert.strictEqual(service.sessionChanged, true)
   })
@@ -41,35 +41,69 @@ describe('PikkuSessionService', () => {
     assert.deepStrictEqual(frozen, { userId: 'user-1' })
   })
 
-  test('should only freeze initial once', () => {
+  test('should only freeze initial once', async () => {
     const service = new PikkuSessionService()
     service.setInitial({ userId: 'user-1' })
     service.freezeInitial()
-    service.set({ userId: 'user-2' })
+    await 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 () => {
+  test('should persist to sessionStore on set when pikkuUserId is set', async () => {
+    let storedId: string | undefined
     let storedSession: any
     const store = {
-      setUserSession: (id: string, session: any) => {
+      get: async () => undefined,
+      set: async (id: string, session: any) => {
+        storedId = id
         storedSession = session
       },
-      getChannelAndSession: (id: string) => ({ session: { userId: 'stored' } }),
+      clear: async () => {},
     }
-    const service = new PikkuSessionService(store as any, 'ch-1')
-    service.set({ userId: 'new' })
+    const service = new PikkuSessionService(store as any)
+    service.setPikkuUserId('user-123')
+    await service.set({ userId: 'new' })
+    assert.strictEqual(storedId, 'user-123')
     assert.deepStrictEqual(storedSession, { userId: 'new' })
+  })
 
-    const session = service.get()
-    assert.deepStrictEqual(session, { userId: 'stored' })
+  test('should not persist to sessionStore when pikkuUserId is not set', async () => {
+    let setCalled = false
+    const store = {
+      get: async () => undefined,
+      set: async () => {
+        setCalled = true
+      },
+      clear: async () => {},
+    }
+    const service = new PikkuSessionService(store as any)
+    await service.set({ userId: 'new' })
+    assert.strictEqual(setCalled, false)
+  })
+
+  test('should clear from sessionStore when pikkuUserId is set', async () => {
+    let clearedId: string | undefined
+    const store = {
+      get: async () => undefined,
+      set: async () => {},
+      clear: async (id: string) => {
+        clearedId = id
+      },
+    }
+    const service = new PikkuSessionService(store as any)
+    service.setPikkuUserId('user-123')
+    service.setInitial({ userId: 'user-123' })
+    await service.clear()
+    assert.strictEqual(clearedId, 'user-123')
+    assert.strictEqual(service.get(), undefined)
+  })
+
+  test('getPikkuUserId should return set value', () => {
+    const service = new PikkuSessionService()
+    assert.strictEqual(service.getPikkuUserId(), undefined)
+    service.setPikkuUserId('user-456')
+    assert.strictEqual(service.getPikkuUserId(), 'user-456')
   })
 })