@pikku/core 0.12.9 → 0.12.10

package/dist/wirings/oauth2/oauth2-routes.js

@@ -0,0 +1,146 @@
+import { OAuth2Client } from './oauth2-client.js';
+const TOKEN_EXPIRY_BUFFER_MS = 60_000;
+function getCredentialMeta(ctx, name) {
+    const meta = ctx.credentialsMeta[name];
+    if (!meta) {
+        throw new Error(`Credential '${name}' not found`);
+    }
+    if (!meta.oauth2) {
+        throw new Error(`Credential '${name}' is not an OAuth2 credential`);
+    }
+    return meta;
+}
+/**
+ * Creates OAuth2 route handlers for user credential management.
+ *
+ * Returns individual handler functions for connect/callback/disconnect/status
+ * that handle the OAuth2 authorization code flow and store tokens in CredentialService.
+ *
+ * @example
+ * ```typescript
+ * const oauth2 = createOAuth2Handler({ credentialsMeta })
+ *
+ * const oauth2Routes = defineHTTPRoutes({
+ *   auth: true,
+ *   basePath: '/credentials',
+ *   routes: {
+ *     connect: { method: 'get', route: '/:name/connect', func: oauth2.connect },
+ *     callback: { method: 'get', route: '/:name/callback', func: oauth2.callback, auth: false },
+ *     disconnect: { method: 'delete', route: '/:name', func: oauth2.disconnect },
+ *     status: { method: 'get', route: '/:name/status', func: oauth2.status },
+ *   },
+ * })
+ *
+ * wireHTTPRoutes({ routes: { credentials: oauth2Routes } })
+ * ```
+ */
+export const createOAuth2Handler = (options) => {
+    const basePath = options.basePath ?? '/credentials';
+    const ctx = {
+        credentialsMeta: options.credentialsMeta,
+        basePath,
+    };
+    const connectHandler = async (services, _data, wire) => {
+        const { name } = wire.http.request.params();
+        const meta = getCredentialMeta(ctx, name);
+        const queryParams = wire.http.request.query();
+        const redirectUrl = queryParams.redirect_url || queryParams.redirect;
+        const oauth2Client = new OAuth2Client(meta.oauth2, meta.oauth2.appCredentialSecretId, services.secrets);
+        const userId = wire.session?.userId;
+        if (!userId) {
+            throw new Error('Authentication required for OAuth2 connect');
+        }
+        const state = await services.jwt.encode({ value: 10, unit: 'minute' }, {
+            userId,
+            credentialName: name,
+            redirectUrl,
+        });
+        let origin = wire.http.request.header('origin');
+        if (!origin) {
+            const host = wire.http.request.header('host');
+            if (!host) {
+                throw new Error('Unable to determine request origin for OAuth2 callback');
+            }
+            const protocol = wire.http.request.header('x-forwarded-proto') || 'http';
+            origin = `${protocol}://${host}`;
+        }
+        const callbackUrl = `${origin}${basePath}/${name}/callback`;
+        const authUrl = await oauth2Client.getAuthorizationUrl(state, callbackUrl);
+        return Response.redirect(authUrl, 302);
+    };
+    const callbackHandler = async (services, _data, wire) => {
+        const { name } = wire.http.request.params();
+        const meta = getCredentialMeta(ctx, name);
+        const queryParams = wire.http.request.query();
+        const code = queryParams.code;
+        const state = queryParams.state;
+        if (!code || !state) {
+            throw new Error('Missing code or state parameter');
+        }
+        let statePayload;
+        try {
+            statePayload = await services.jwt.decode(state);
+        }
+        catch {
+            throw new Error('Invalid or expired OAuth2 state');
+        }
+        if (statePayload.credentialName !== name) {
+            throw new Error('Credential name mismatch in state');
+        }
+        const oauth2Client = new OAuth2Client(meta.oauth2, meta.oauth2.appCredentialSecretId, services.secrets);
+        let origin = wire.http.request.header('origin');
+        if (!origin) {
+            const host = wire.http.request.header('host');
+            if (!host) {
+                throw new Error('Unable to determine request origin for OAuth2 callback');
+            }
+            const protocol = wire.http.request.header('x-forwarded-proto') || 'http';
+            origin = `${protocol}://${host}`;
+        }
+        const callbackUrl = `${origin}${basePath}/${name}/callback`;
+        const tokens = await oauth2Client.exchangeCode(code, callbackUrl);
+        await services.credentialService.set(name, tokens, statePayload.userId);
+        services.logger.info(`OAuth2 tokens stored for user '${statePayload.userId}', credential '${name}'`);
+        if (statePayload.redirectUrl) {
+            return Response.redirect(statePayload.redirectUrl, 302);
+        }
+        else {
+            return { success: true, credentialName: name };
+        }
+    };
+    const disconnectHandler = async (services, _data, wire) => {
+        const { name } = wire.http.request.params();
+        const userId = wire.session?.userId;
+        if (!userId) {
+            throw new Error('Authentication required');
+        }
+        await services.credentialService.delete(name, userId);
+        services.logger.info(`OAuth2 credential '${name}' disconnected for user '${userId}'`);
+        return { success: true };
+    };
+    const statusHandler = async (services, _data, wire) => {
+        const { name } = wire.http.request.params();
+        const userId = wire.session?.userId;
+        if (!userId) {
+            throw new Error('Authentication required');
+        }
+        const credential = await services.credentialService.get(name, userId);
+        if (!credential) {
+            return { connected: false };
+        }
+        return {
+            connected: true,
+            hasRefreshToken: !!credential.refreshToken,
+            expiresAt: credential.expiresAt,
+            isExpired: credential.expiresAt
+                ? credential.expiresAt < Date.now() + TOKEN_EXPIRY_BUFFER_MS
+                : false,
+        };
+    };
+    return {
+        connect: { func: connectHandler },
+        callback: { func: callbackHandler },
+        disconnect: { func: disconnectHandler },
+        status: { func: statusHandler },
+    };
+};

package/dist/wirings/oauth2/oauth2.types.d.ts

@@ -37,29 +37,3 @@ export type OAuth2Config = {
     /** Additional query parameters for authorization URL */
     additionalParams?: Record<string, string>;
 };
-/**
- * Configuration for wireOAuth2Credential.
- * Combines standard credential fields with OAuth2-specific config.
- */
-export type CoreOAuth2Credential = {
-    /** Unique identifier for this credential */
-    name: string;
-    /** Human-readable name for UI display */
-    displayName: string;
-    /** Optional description for UI */
-    description?: string;
-    /** Key used with SecretService to retrieve app credentials (clientId/clientSecret) */
-    secretId: string;
-    /** Where access/refresh tokens are stored */
-    tokenSecretId: string;
-    /** OAuth2 authorization URL */
-    authorizationUrl: string;
-    /** OAuth2 token exchange URL */
-    tokenUrl: string;
-    /** Required scopes */
-    scopes: string[];
-    /** Use PKCE flow */
-    pkce?: boolean;
-    /** Additional query parameters for authorization URL */
-    additionalParams?: Record<string, string>;
-};

package/dist/wirings/workflow/graph/graph-runner.d.ts

@@ -1,4 +1,4 @@
-import type { PikkuWorkflowService } from '../pikku-workflow-service.js';
+import { type PikkuWorkflowService } from '../pikku-workflow-service.js';
 import type { WorkflowRuntimeMeta, WorkflowRunWire } from '../workflow.types.js';
 export declare class ChildWorkflowStartedException extends Error {
     parentRunId: string;

package/dist/wirings/workflow/graph/graph-runner.js

@@ -1,3 +1,4 @@
+import { WorkflowAsyncException, WorkflowSuspendedException, } from '../pikku-workflow-service.js';
 import { pikkuState, getSingletonServices } from '../../../pikku-state.js';
 import { RPCNotFoundError } from '../../rpc/rpc-runner.js';
 export class ChildWorkflowStartedException extends Error {
@@ -362,6 +363,7 @@ export async function executeGraphStep(workflowService, rpcService, runId, stepI
         else {
             result = await rpcService.rpcWithWire(rpcName, data, {
                 graph: graphWire,
+                workflow: workflowService.createWorkflowWire(graphName, runId, rpcService),
             });
         }
         if (wireState.branchKey) {
@@ -370,6 +372,10 @@ export async function executeGraphStep(workflowService, rpcService, runId, stepI
         return result;
     }
     catch (error) {
+        if (error instanceof WorkflowAsyncException ||
+            error instanceof WorkflowSuspendedException) {
+            throw error;
+        }
         if (error instanceof ChildWorkflowStartedException) {
             throw error;
         }
@@ -447,6 +453,7 @@ async function executeGraphNodeInline(workflowService, rpcService, runId, graphN
         else {
             result = await rpcService.rpcWithWire(rpcName, input, {
                 graph: graphWire,
+                workflow: workflowService.createWorkflowWire(graphName, runId, rpcService),
             });
         }
         if (wireState.branchKey) {
@@ -455,6 +462,10 @@ async function executeGraphNodeInline(workflowService, rpcService, runId, graphN
         await workflowService.setStepResult(stepState.stepId, result);
     }
     catch (error) {
+        if (error instanceof WorkflowAsyncException ||
+            error instanceof WorkflowSuspendedException) {
+            throw error;
+        }
         if (error instanceof RPCNotFoundError) {
             await workflowService.setStepError(stepState.stepId, error);
             await workflowService.updateRunStatus(runId, 'suspended', undefined, {
@@ -575,6 +586,10 @@ export async function runWorkflowGraph(workflowService, graphName, triggerInput,
                 await continueGraphInline(workflowService, rpcService, runId, graphName, nodes, triggerInput, entryNodes);
             }
             catch (error) {
+                if (error instanceof WorkflowAsyncException ||
+                    error instanceof WorkflowSuspendedException) {
+                    return;
+                }
                 await workflowService.updateRunStatus(runId, 'failed', undefined, {
                     message: error.message,
                     stack: error.stack || '',

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -1,5 +1,5 @@
 import type { SerializedError } from '../../types/core.types.js';
-import type { StepState, WorkflowRun, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
+import type { PikkuWorkflowWire, StepState, WorkflowRun, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 /**
@@ -269,7 +269,7 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     private sleepStep;
     private getSuspendStepName;
     private suspendStep;
-    private createWorkflowWire;
+    createWorkflowWire(name: string, runId: string, rpcService: any): PikkuWorkflowWire;
     private verifyStepName;
     private getConfig;
 }

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

@@ -373,17 +373,49 @@ export class PikkuWorkflowService {
                 }
                 const meta = pikkuState(null, 'workflows', 'meta');
                 const workflowMeta = meta[run.workflow];
-                if (workflowMeta?.nodes && stepName in workflowMeta.nodes) {
+                const isGraphWorkflow = workflowMeta?.source === 'graph' ||
+                    workflowMeta?.source === 'ai-agent';
+                if (isGraphWorkflow &&
+                    workflowMeta?.nodes &&
+                    stepName in workflowMeta.nodes) {
                     result = await executeGraphStep(this, rpcService, runId, stepState.stepId, stepName, rpcName, data, run.workflow);
                 }
                 else {
-                    result = await rpcService.rpcWithWire(rpcName, data, {
-                        workflowStep: {
-                            runId,
-                            stepId: stepState.stepId,
-                            attemptCount: stepState.attemptCount,
-                        },
-                    });
+                    // Check if rpcName refers to a sub-workflow
+                    const subWorkflowMeta = meta[rpcName];
+                    if (subWorkflowMeta) {
+                        const childWire = {
+                            type: 'workflow',
+                            id: rpcName,
+                            parentRunId: runId,
+                            parentStepId: stepState.stepId,
+                        };
+                        const shouldInline = subWorkflowMeta.inline || !getSingletonServices()?.queueService;
+                        const { runId: childRunId } = await this.startWorkflow(rpcName, data, childWire, rpcService, { inline: shouldInline });
+                        await this.setStepChildRunId(stepState.stepId, childRunId);
+                        if (shouldInline) {
+                            const childRun = await this.getRun(childRunId);
+                            if (childRun?.status === 'failed') {
+                                throw new Error(childRun.error?.message || 'Sub-workflow failed');
+                            }
+                            if (childRun?.status === 'cancelled') {
+                                throw new Error('Sub-workflow was cancelled');
+                            }
+                            result = childRun?.output;
+                        }
+                        else {
+                            throw new ChildWorkflowStartedException(runId, stepState.stepId, childRunId);
+                        }
+                    }
+                    else {
+                        result = await rpcService.rpcWithWire(rpcName, data, {
+                            workflowStep: {
+                                runId,
+                                stepId: stepState.stepId,
+                                attemptCount: stepState.attemptCount,
+                            },
+                        });
+                    }
                 }
                 // Store result and mark succeeded
                 await this.setStepResult(stepState.stepId, result);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.9",
+  "version": "0.12.10",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -35,6 +35,7 @@
     "./cli": "./dist/wirings/cli/index.js",
     "./cli/channel": "./dist/wirings/cli/channel/index.js",
     "./node": "./dist/wirings/node/index.js",
+    "./credential": "./dist/wirings/credential/index.js",
     "./secret": "./dist/wirings/secret/index.js",
     "./variable": "./dist/wirings/variable/index.js",
     "./oauth2": "./dist/wirings/oauth2/index.js",

package/src/function/function-runner.ts

@@ -28,6 +28,8 @@ import { parseVersionedId } from '../version.js'
 import type { SessionService } from '../services/user-session-service.js'
 import { createFunctionSessionWireProps } from '../services/user-session-service.js'
 import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js'
+import type { PikkuCredentialWireService } from '../services/credential-wire-service.js'
+import { createWireServicesCredentialWireProps } from '../services/credential-wire-service.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { closeWireServices } from '../utils.js'
 
@@ -146,6 +148,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
     tags = [],
     wire,
     sessionService,
+    credentialWireService,
     packageName = null,
   }: {
     singletonServices: CoreSingletonServices
@@ -162,6 +165,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
     tags?: string[]
     wire: PikkuWire
     sessionService?: SessionService<CoreUserSession>
+    credentialWireService?: PikkuCredentialWireService
     packageName?: string | null
   }
 ): Promise<Out> => {
@@ -312,6 +316,13 @@ export const runPikkuFunc = async <In = any, Out = any>(
       })
     }
 
+    if (credentialWireService) {
+      Object.assign(
+        resolvedWire,
+        createWireServicesCredentialWireProps(credentialWireService)
+      )
+    }
+
     const wireServices = await resolvedCreateWireServices?.(
       resolvedSingletonServices,
       resolvedWire

package/src/services/credential-service.ts

@@ -0,0 +1,44 @@
+/**
+ * Interface for managing dynamic/managed credentials.
+ * Used for OAuth tokens, per-user API keys, and other credentials
+ * that change at runtime (as opposed to SecretService which is for
+ * static, developer-configured values).
+ */
+export interface CredentialService {
+  /**
+   * Retrieves a credential by name and optional user ID.
+   * @param name - The credential name (e.g. 'stripe', 'google-sheets').
+   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
+   * @returns The credential value, or null if not found.
+   */
+  get<T = unknown>(name: string, userId?: string): Promise<T | null>
+
+  /**
+   * Stores a credential.
+   * @param name - The credential name.
+   * @param value - The credential value to store.
+   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
+   */
+  set(name: string, value: unknown, userId?: string): Promise<void>
+
+  /**
+   * Deletes a credential.
+   * @param name - The credential name.
+   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
+   */
+  delete(name: string, userId?: string): Promise<void>
+
+  /**
+   * Checks if a credential exists.
+   * @param name - The credential name.
+   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
+   */
+  has(name: string, userId?: string): Promise<boolean>
+
+  /**
+   * Retrieves all credentials for a user.
+   * @param userId - The user ID.
+   * @returns A record of credential name to value.
+   */
+  getAll(userId: string): Promise<Record<string, unknown>>
+}

package/src/services/credential-wire-service.ts

@@ -0,0 +1,44 @@
+export class PikkuCredentialWireService {
+  private credentials: Record<string, unknown> = {}
+
+  set(name: string, value: unknown): void {
+    this.credentials[name] = value
+  }
+
+  getAll(): Record<string, unknown> {
+    return this.credentials
+  }
+
+  getScoped(allowedNames: string[]): Record<string, unknown> {
+    const scoped: Record<string, unknown> = {}
+    for (const name of allowedNames) {
+      if (name in this.credentials) {
+        scoped[name] = this.credentials[name]
+      }
+    }
+    return scoped
+  }
+}
+
+export function createMiddlewareCredentialWireProps(
+  credentialWire: PikkuCredentialWireService
+) {
+  return {
+    setCredential: (name: string, value: unknown) =>
+      credentialWire.set(name, value),
+  }
+}
+
+export function createWireServicesCredentialWireProps(
+  credentialWire: PikkuCredentialWireService,
+  allowedNames?: string[]
+) {
+  return {
+    setCredential: (name: string, value: unknown) =>
+      credentialWire.set(name, value),
+    getCredentials: () =>
+      allowedNames
+        ? credentialWire.getScoped(allowedNames)
+        : credentialWire.getAll(),
+  }
+}

package/src/services/index.ts

@@ -10,8 +10,14 @@ export {
   createFunctionSessionWireProps,
 } from './user-session-service.js'
 export { TypedSecretService } from './typed-secret-service.js'
+export {
+  PikkuCredentialWireService,
+  createMiddlewareCredentialWireProps,
+  createWireServicesCredentialWireProps,
+} from './credential-wire-service.js'
 export { TypedVariablesService } from './typed-variables-service.js'
 export { LocalSecretService } from './local-secrets.js'
+export { LocalCredentialService } from './local-credential-service.js'
 export { LocalVariablesService } from './local-variables.js'
 export { ConsoleLogger } from './logger-console.js'
 export { InMemoryWorkflowService } from './in-memory-workflow-service.js'
@@ -53,4 +59,10 @@ export type {
   CredentialStatus,
   CredentialMeta,
 } from './typed-secret-service.js'
+export type { CredentialService } from './credential-service.js'
+export { TypedCredentialService } from './typed-credential-service.js'
+export type {
+  CredentialStatusInfo,
+  CredentialMetaInfo,
+} from './typed-credential-service.js'
 export type { VariableStatus, VariableMeta } from './typed-variables-service.js'

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

@@ -0,0 +1,41 @@
+import type { CredentialService } from './credential-service.js'
+
+export class LocalCredentialService implements CredentialService {
+  private store: Map<string, unknown> = new Map()
+
+  private makeKey(name: string, userId?: string): string {
+    return userId ? `${userId}:${name}` : name
+  }
+
+  async get<T = unknown>(name: string, userId?: string): Promise<T | null> {
+    const key = this.makeKey(name, userId)
+    const value = this.store.get(key)
+    return (value as T) ?? null
+  }
+
+  async set(name: string, value: unknown, userId?: string): Promise<void> {
+    const key = this.makeKey(name, userId)
+    this.store.set(key, value)
+  }
+
+  async delete(name: string, userId?: string): Promise<void> {
+    const key = this.makeKey(name, userId)
+    this.store.delete(key)
+  }
+
+  async has(name: string, userId?: string): Promise<boolean> {
+    const key = this.makeKey(name, userId)
+    return this.store.has(key)
+  }
+
+  async getAll(userId: string): Promise<Record<string, unknown>> {
+    const prefix = `${userId}:`
+    const result: Record<string, unknown> = {}
+    for (const [key, value] of this.store) {
+      if (key.startsWith(prefix)) {
+        result[key.slice(prefix.length)] = value
+      }
+    }
+    return result
+  }
+}

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

@@ -0,0 +1,75 @@
+import type { CredentialService } from './credential-service.js'
+
+export interface CredentialStatusInfo {
+  name: string
+  displayName: string
+  isConfigured: boolean
+  type: 'singleton' | 'wire'
+  oauth2?: boolean
+}
+
+export type CredentialMetaInfo = {
+  name: string
+  displayName: string
+  type: 'singleton' | 'wire'
+  oauth2?: boolean
+}
+
+export class TypedCredentialService<TMap = Record<string, unknown>>
+  implements CredentialService
+{
+  constructor(
+    private credentials: CredentialService,
+    private credentialsMeta: Record<string, CredentialMetaInfo>
+  ) {}
+
+  async get<K extends keyof TMap & string>(
+    name: K,
+    userId?: string
+  ): Promise<TMap[K] | null>
+  async get<T = unknown>(name: string, userId?: string): Promise<T | null>
+  async get(name: string, userId?: string): Promise<unknown> {
+    return this.credentials.get(name, userId)
+  }
+
+  async set<K extends string>(
+    name: K,
+    value: K extends keyof TMap ? TMap[K] : unknown,
+    userId?: string
+  ): Promise<void> {
+    return this.credentials.set(name, value, userId)
+  }
+
+  async delete(name: string, userId?: string): Promise<void> {
+    return this.credentials.delete(name, userId)
+  }
+
+  async has(name: string, userId?: string): Promise<boolean> {
+    return this.credentials.has(name, userId)
+  }
+
+  async getAll(userId: string): Promise<Record<string, unknown>> {
+    return this.credentials.getAll(userId)
+  }
+
+  async getAllStatus(userId?: string): Promise<CredentialStatusInfo[]> {
+    const results: CredentialStatusInfo[] = []
+
+    for (const [name, meta] of Object.entries(this.credentialsMeta)) {
+      results.push({
+        name,
+        displayName: meta.displayName,
+        isConfigured: await this.credentials.has(name, userId),
+        type: meta.type,
+        oauth2: meta.oauth2,
+      })
+    }
+
+    return results
+  }
+
+  async getMissing(userId?: string): Promise<CredentialStatusInfo[]> {
+    const all = await this.getAllStatus(userId)
+    return all.filter((c) => !c.isConfigured)
+  }
+}