@pikku/core 0.11.2 → 0.12.0

package/dist/wirings/oauth2/oauth2-client.d.ts

@@ -0,0 +1,47 @@
+import { OAuth2Token } from './oauth2.types.js';
+import { OAuth2CredentialConfig } from '../secret/secret.types.js';
+import { SecretService } from '../../services/secret-service.js';
+export declare class OAuth2Client {
+    private oauth2Config;
+    private appCredentialSecretId;
+    private secrets;
+    private cachedToken;
+    private cachedAppCredential;
+    private refreshPromise;
+    constructor(oauth2Config: OAuth2CredentialConfig, appCredentialSecretId: string, secrets: SecretService);
+    /**
+     * Make an authenticated request. Handles token caching and 401 refresh.
+     */
+    request(url: string, options?: RequestInit, timeoutMs?: number): Promise<Response>;
+    /**
+     * Get cached token or load from secrets.
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Refresh token and update cache.
+     * Uses a promise lock to prevent concurrent refresh attempts.
+     */
+    private refreshAndGetToken;
+    /**
+     * Perform the actual token refresh.
+     */
+    private doRefreshToken;
+    /**
+     * Check if token is valid (not expired).
+     */
+    private isTokenValid;
+    /**
+     * Get app credentials (cached).
+     */
+    private getAppCredential;
+    /**
+     * Generate OAuth2 authorization URL.
+     * Used by CLI during `pikku oauth connect`.
+     */
+    getAuthorizationUrl(state: string, redirectUri: string): Promise<string>;
+    /**
+     * Exchange authorization code for tokens.
+     * Used by CLI during `pikku oauth connect`.
+     */
+    exchangeCode(code: string, redirectUri: string): Promise<OAuth2Token>;
+}

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

@@ -0,0 +1,267 @@
+/**
+ * OAuth2 client that acts as a service.
+ * Created once in createSingletonServices, handles token caching and refresh internally.
+ * Functions use it directly via oauth.request().
+ *
+ * @example
+ * ```typescript
+ * // In services.ts
+ * export const createSingletonServices = async (config, { secrets }) => {
+ *   return {
+ *     slackOAuth: new OAuth2Client(
+ *       { tokenSecretId: 'SLACK_TOKENS', authorizationUrl: '...', tokenUrl: '...', scopes: [] },
+ *       'SLACK_APP_CREDS',
+ *       secrets
+ *     ),
+ *   }
+ * }
+ *
+ * // In function
+ * export const postMessage = pikkuFunc(async ({ slackOAuth }, { channel, text }) => {
+ *   const response = await slackOAuth.request('https://slack.com/api/chat.postMessage', {
+ *     method: 'POST',
+ *     body: JSON.stringify({ channel, text }),
+ *   })
+ *   return response.json()
+ * })
+ * ```
+ */
+const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Helper to fetch with a timeout using AbortController.
+ */
+async function fetchWithTimeout(url, options, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, {
+            ...options,
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+export class OAuth2Client {
+    oauth2Config;
+    appCredentialSecretId;
+    secrets;
+    cachedToken = null;
+    cachedAppCredential = null;
+    refreshPromise = null;
+    constructor(oauth2Config, appCredentialSecretId, secrets) {
+        this.oauth2Config = oauth2Config;
+        this.appCredentialSecretId = appCredentialSecretId;
+        this.secrets = secrets;
+    }
+    /**
+     * Make an authenticated request. Handles token caching and 401 refresh.
+     */
+    async request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        const token = await this.getAccessToken();
+        const response = await fetchWithTimeout(url, {
+            ...options,
+            headers: {
+                ...options?.headers,
+                Authorization: `Bearer ${token}`,
+            },
+        }, timeoutMs);
+        // Auto-retry on 401 after refresh
+        if (response.status === 401) {
+            const newToken = await this.refreshAndGetToken();
+            return fetchWithTimeout(url, {
+                ...options,
+                headers: {
+                    ...options?.headers,
+                    Authorization: `Bearer ${newToken}`,
+                },
+            }, timeoutMs);
+        }
+        return response;
+    }
+    /**
+     * Get cached token or load from secrets.
+     */
+    async getAccessToken() {
+        // Return cached token if valid
+        if (this.cachedToken) {
+            if (this.isTokenValid(this.cachedToken)) {
+                return this.cachedToken.accessToken;
+            }
+            // Token expired, try to refresh
+            if (this.cachedToken.refreshToken) {
+                return this.refreshAndGetToken();
+            }
+            // Token expired and no refresh token available
+            throw new Error('OAuth2 token expired and no refresh token available');
+        }
+        // Load from secrets
+        const token = await this.secrets.getSecretJSON(this.oauth2Config.tokenSecretId);
+        this.cachedToken = token;
+        // Check if loaded token is expired and needs refresh
+        if (!this.isTokenValid(token)) {
+            if (token.refreshToken) {
+                return this.refreshAndGetToken();
+            }
+            // Token expired and no refresh token available
+            throw new Error('OAuth2 token expired and no refresh token available');
+        }
+        return token.accessToken;
+    }
+    /**
+     * Refresh token and update cache.
+     * Uses a promise lock to prevent concurrent refresh attempts.
+     */
+    async refreshAndGetToken() {
+        // If already refreshing, wait for that to complete
+        if (this.refreshPromise) {
+            const token = await this.refreshPromise;
+            return token.accessToken;
+        }
+        // Start refresh
+        this.refreshPromise = this.doRefreshToken();
+        try {
+            const token = await this.refreshPromise;
+            this.cachedToken = token;
+            return token.accessToken;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    /**
+     * Perform the actual token refresh.
+     */
+    async doRefreshToken() {
+        if (!this.cachedToken?.refreshToken) {
+            throw new Error('No refresh token available');
+        }
+        const appCredential = await this.getAppCredential();
+        const params = new URLSearchParams({
+            grant_type: 'refresh_token',
+            refresh_token: this.cachedToken.refreshToken,
+            client_id: appCredential.clientId,
+        });
+        if (appCredential.clientSecret) {
+            params.set('client_secret', appCredential.clientSecret);
+        }
+        const response = await fetchWithTimeout(this.oauth2Config.tokenUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: params.toString(),
+        });
+        if (!response.ok) {
+            throw new Error(`Token refresh failed: ${response.status}`);
+        }
+        const data = await response.json();
+        if (!data.access_token || typeof data.access_token !== 'string') {
+            throw new Error('Invalid token response: missing access_token');
+        }
+        const token = {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token || this.cachedToken.refreshToken,
+            expiresAt: data.expires_in
+                ? Date.now() + data.expires_in * 1000
+                : undefined,
+            tokenType: data.token_type || 'Bearer',
+            scope: data.scope,
+        };
+        // Cache and persist the refreshed token
+        this.cachedToken = token;
+        await this.secrets.setSecretJSON(this.oauth2Config.tokenSecretId, token);
+        return token;
+    }
+    /**
+     * Check if token is valid (not expired).
+     */
+    isTokenValid(token) {
+        if (!token.expiresAt) {
+            return true; // No expiry info, assume valid
+        }
+        // Add 60 second buffer to account for clock skew
+        return token.expiresAt > Date.now() + 60000;
+    }
+    /**
+     * Get app credentials (cached).
+     */
+    async getAppCredential() {
+        if (this.cachedAppCredential) {
+            return this.cachedAppCredential;
+        }
+        this.cachedAppCredential =
+            await this.secrets.getSecretJSON(this.appCredentialSecretId);
+        return this.cachedAppCredential;
+    }
+    // ========================================
+    // CLI-only methods (for pikku oauth connect)
+    // ========================================
+    /**
+     * Generate OAuth2 authorization URL.
+     * Used by CLI during `pikku oauth connect`.
+     */
+    async getAuthorizationUrl(state, redirectUri) {
+        const appCredential = await this.getAppCredential();
+        const params = new URLSearchParams({
+            response_type: 'code',
+            client_id: appCredential.clientId,
+            redirect_uri: redirectUri,
+            scope: this.oauth2Config.scopes.join(' '),
+            state,
+        });
+        // Add PKCE if enabled
+        // Note: code_verifier should be stored and passed to exchangeCode
+        // For now, PKCE implementation is simplified
+        // Add any additional params
+        if (this.oauth2Config.additionalParams) {
+            for (const [key, value] of Object.entries(this.oauth2Config.additionalParams)) {
+                params.set(key, value);
+            }
+        }
+        return `${this.oauth2Config.authorizationUrl}?${params.toString()}`;
+    }
+    /**
+     * Exchange authorization code for tokens.
+     * Used by CLI during `pikku oauth connect`.
+     */
+    async exchangeCode(code, redirectUri) {
+        const appCredential = await this.getAppCredential();
+        const params = new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: redirectUri,
+            client_id: appCredential.clientId,
+        });
+        if (appCredential.clientSecret) {
+            params.set('client_secret', appCredential.clientSecret);
+        }
+        const response = await fetchWithTimeout(this.oauth2Config.tokenUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: params.toString(),
+        });
+        if (!response.ok) {
+            throw new Error(`Token exchange failed: ${response.status}`);
+        }
+        const data = await response.json();
+        if (!data.access_token || typeof data.access_token !== 'string') {
+            throw new Error('Invalid token response: missing access_token');
+        }
+        const token = {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token,
+            expiresAt: data.expires_in
+                ? Date.now() + data.expires_in * 1000
+                : undefined,
+            tokenType: data.token_type || 'Bearer',
+            scope: data.scope,
+        };
+        // Cache the token
+        this.cachedToken = token;
+        return token;
+    }
+}

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

@@ -0,0 +1,65 @@
+/**
+ * OAuth2 credential and token types.
+ */
+/**
+ * App credentials for OAuth2 (client ID and secret).
+ * These are typically set once and stored in the secret service.
+ */
+export type OAuth2AppCredential = {
+    clientId: string;
+    clientSecret?: string;
+};
+/**
+ * OAuth2 token data returned from token endpoint.
+ */
+export type OAuth2Token = {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    tokenType: string;
+    scope?: string;
+};
+/**
+ * OAuth2-specific configuration that extends a credential.
+ * This is stored in SecretDefinitionMeta.oauth2 field.
+ */
+export type OAuth2Config = {
+    /** 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>;
+};
+/**
+ * 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/oauth2/oauth2.types.js

@@ -0,0 +1,4 @@
+/**
+ * OAuth2 credential and token types.
+ */
+export {};

package/dist/wirings/oauth2/wire-oauth2-credential.d.ts

@@ -0,0 +1,20 @@
+import { CoreOAuth2Credential } from './oauth2.types.js';
+/**
+ * No-op function for declaring OAuth2 credentials.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing.
+ *
+ * @example
+ * ```typescript
+ * wireOAuth2Credential({
+ *   name: 'slackOAuth',
+ *   displayName: 'Slack OAuth',
+ *   secretId: 'SLACK_OAUTH_APP',
+ *   tokenSecretId: 'SLACK_OAUTH_TOKENS',
+ *   authorizationUrl: 'https://slack.com/oauth/v2/authorize',
+ *   tokenUrl: 'https://slack.com/api/oauth.v2.access',
+ *   scopes: ['chat:write', 'channels:read'],
+ * })
+ * ```
+ */
+export declare const wireOAuth2Credential: (_config: CoreOAuth2Credential) => void;

package/dist/wirings/oauth2/wire-oauth2-credential.js

@@ -0,0 +1,21 @@
+/**
+ * No-op function for declaring OAuth2 credentials.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing.
+ *
+ * @example
+ * ```typescript
+ * wireOAuth2Credential({
+ *   name: 'slackOAuth',
+ *   displayName: 'Slack OAuth',
+ *   secretId: 'SLACK_OAUTH_APP',
+ *   tokenSecretId: 'SLACK_OAUTH_TOKENS',
+ *   authorizationUrl: 'https://slack.com/oauth/v2/authorize',
+ *   tokenUrl: 'https://slack.com/api/oauth.v2.access',
+ *   scopes: ['chat:write', 'channels:read'],
+ * })
+ * ```
+ */
+export const wireOAuth2Credential = (_config) => {
+    // No-op - metadata only, extracted by CLI via AST
+};

package/dist/wirings/queue/index.d.ts

@@ -1,5 +1,5 @@
-export type * from './queue.types.js';
-export { wireQueueWorker, runQueueJob, getQueueWorkers, removeQueueWorker, QueueJobDiscardedError, QueueJobFailedError, } from './queue-runner.js';
+export type { ConfigValidationResult, CoreQueueWorker, JobOptions, PikkuJobConfig, PikkuWorkerConfig, PikkuQueue, QueueJob, QueueJobStatus, QueueService, QueueWorkers, QueueWorkersMeta, } from './queue.types.js';
+export { wireQueueWorker, runQueueJob, createQueueJobRunner, getQueueWorkers, removeQueueWorker, QueueJobDiscardedError, QueueJobFailedError, } from './queue-runner.js';
 export { validateWorkerConfig } from './validate-worker-config.js';
 export type { QueueConfigMapping } from './validate-worker-config.js';
 export { registerQueueWorkers } from './register-queue-helper.js';

package/dist/wirings/queue/index.js

@@ -1,5 +1,5 @@
 // Queue processor management
-export { wireQueueWorker, runQueueJob, getQueueWorkers, removeQueueWorker, QueueJobDiscardedError, QueueJobFailedError, } from './queue-runner.js';
+export { wireQueueWorker, runQueueJob, createQueueJobRunner, getQueueWorkers, removeQueueWorker, QueueJobDiscardedError, QueueJobFailedError, } from './queue-runner.js';
 // Configuration validation
 export { validateWorkerConfig } from './validate-worker-config.js';
 // Queue registration helper

package/dist/wirings/queue/queue-runner.d.ts

@@ -36,3 +36,10 @@ export declare function runQueueJob({ singletonServices, createWireServices, job
     job: QueueJob;
     updateProgress?: (progress: number | string | object) => Promise<void>;
 }): Promise<void>;
+export declare const createQueueJobRunner: ({ singletonServices, createWireServices, }: {
+    singletonServices: CoreServices;
+    createWireServices?: CreateWireServices;
+}) => ({ job, updateProgress, }: {
+    job: QueueJob;
+    updateProgress?: (progress: number | string | object) => Promise<void>;
+}) => Promise<void>;

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

@@ -1,4 +1,5 @@
 import { getErrorResponse, PikkuError } from '../../errors/error-handler.js';
+import { PikkuMissingMetaError } from '../../errors/errors.js';
 import { pikkuState } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 /**
@@ -33,12 +34,12 @@ export class QueueJobDiscardedError extends PikkuError {
 export const wireQueueWorker = (queueWorker) => {
     // Get processor metadata
     const meta = pikkuState(null, 'queue', 'meta');
-    const processorMeta = meta[queueWorker.queueName];
+    const processorMeta = meta[queueWorker.name];
     if (!processorMeta) {
-        throw new Error(`Queue processor metadata not found for '${queueWorker.queueName}'. Make sure to run the CLI to generate metadata.`);
+        throw new PikkuMissingMetaError(`Missing generated metadata for queue worker '${queueWorker.name}'`);
     }
     // Register the function with pikku
-    addFunction(processorMeta.pikkuFuncName, {
+    addFunction(processorMeta.pikkuFuncId, {
         func: queueWorker.func.func,
         auth: queueWorker.func.auth,
         permissions: queueWorker.func.permissions,
@@ -47,7 +48,7 @@ export const wireQueueWorker = (queueWorker) => {
     });
     // Store processor definition in state - runtime adapters will pick this up
     const registrations = pikkuState(null, 'queue', 'registrations');
-    registrations.set(queueWorker.queueName, queueWorker);
+    registrations.set(queueWorker.name, queueWorker);
 };
 /**
  * Get all registered queue processors
@@ -74,7 +75,7 @@ export async function runQueueJob({ singletonServices, createWireServices, job,
     const meta = pikkuState(null, 'queue', 'meta');
     const processorMeta = meta[job.queueName];
     if (!processorMeta) {
-        throw new Error(`Processor metadata not found for: ${job.queueName}`);
+        throw new PikkuMissingMetaError(`Missing generated metadata for queue worker '${job.queueName}'`);
     }
     // Get the queue worker registration to access middleware
     const registrations = pikkuState(null, 'queue', 'registrations');
@@ -104,7 +105,7 @@ export async function runQueueJob({ singletonServices, createWireServices, job,
             queue,
         };
         // Execute the pikku function with the job data
-        const result = await runPikkuFunc('queue', job.queueName, processorMeta.pikkuFuncName, {
+        const result = await runPikkuFunc('queue', job.queueName, processorMeta.pikkuFuncId, {
             singletonServices,
             createWireServices,
             auth: false,
@@ -127,3 +128,13 @@ export async function runQueueJob({ singletonServices, createWireServices, job,
         throw error;
     }
 }
+export const createQueueJobRunner = ({ singletonServices, createWireServices, }) => {
+    return async ({ job, updateProgress, }) => {
+        await runQueueJob({
+            singletonServices,
+            createWireServices,
+            job,
+            updateProgress,
+        });
+    };
+};

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

@@ -1,6 +1,7 @@
 import { CommonWireMeta } from '../../types/core.types.js';
 import { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import { QueueConfigMapping } from './validate-worker-config.js';
+import { Logger } from '../../services/logger.js';
 /**
  * Configuration for queue workers - how jobs are processed
  */
@@ -124,6 +125,11 @@ export interface QueueWorkers {
     supportsResults: boolean;
     /** Configuration mapping for validation */
     configMappings: QueueConfigMapping;
+    /** Set runtime queue job runner callback and logger */
+    setJobRunner(runJob: (params: {
+        job: QueueJob;
+        updateProgress?: (progress: number | string | object) => Promise<void>;
+    }) => Promise<void>, logger: Logger): void;
     /** Scan state and register all compatible processors */
     registerQueues(): Promise<Record<string, ConfigValidationResult[]>>;
 }
@@ -131,14 +137,14 @@ export interface QueueWorkers {
  * Queue processor metadata
  */
 export type QueueWorkersMeta = Record<string, CommonWireMeta & {
-    queueName: string;
+    name: string;
     config?: PikkuWorkerConfig;
 }>;
 /**
  * Core queue processor definition
  */
 export type CoreQueueWorker<PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> = CorePikkuFunctionConfig<any, any, any>> = {
-    queueName: string;
+    name: string;
     func: PikkuFunctionConfig;
     config?: PikkuWorkerConfig;
     errors?: string[];

package/dist/wirings/rpc/index.d.ts

@@ -1,2 +1,2 @@
-export { PikkuRPCService, rpcService } from './rpc-runner.js';
+export { PikkuRPCService, rpcService, RPCNotFoundError } from './rpc-runner.js';
 export type { PikkuRPC, RPCMeta } from './rpc-types.js';

package/dist/wirings/rpc/index.js

@@ -1 +1 @@
-export { PikkuRPCService, rpcService } from './rpc-runner.js';
+export { PikkuRPCService, rpcService, RPCNotFoundError } from './rpc-runner.js';

package/dist/wirings/rpc/rpc-runner.d.ts

@@ -1,11 +1,20 @@
-import { CoreServices, PikkuWire } from '../../types/core.types.js';
+import { CoreServices, CoreSingletonServices, PikkuWire } from '../../types/core.types.js';
+import type { SessionService } from '../../services/user-session-service.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import { PikkuError } from '../../errors/error-handler.js';
 import { PikkuRPC } from './rpc-types.js';
+export declare class RPCNotFoundError extends PikkuError {
+    readonly rpcName: string;
+    constructor(rpcName: string);
+}
+import type { AIAgentInput } from '../ai-agent/ai-agent.types.js';
 export declare class ContextAwareRPCService {
     private services;
     private wire;
     private options;
     constructor(services: CoreServices, wire: PikkuWire, options: {
         requiresAuth?: boolean;
+        sessionService?: SessionService<CoreUserSession>;
     });
     rpcExposed(funcName: string, data: any): Promise<any>;
     rpc<In = any, Out = any>(funcName: string, data: In): Promise<Out>;
@@ -17,15 +26,34 @@ export declare class ContextAwareRPCService {
      */
     private invokeExternalPackageFunction;
     rpcWithWire<In = any, Out = any>(rpcName: string, data: In, wire: PikkuWire): Promise<Out>;
-    startWorkflow<In = any>(workflowName: string, input: In): Promise<{
+    startWorkflow<In = any>(workflowName: string, input: In, options?: {
+        startNode?: string;
+        wire?: {
+            type: string;
+            id?: string;
+            parentRunId?: string;
+        };
+    }): Promise<{
+        runId: string;
+    }>;
+    agent(agentName: string, input: AIAgentInput): Promise<{
         runId: string;
+        result: unknown;
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+        };
     }>;
+    remote<In = any, Out = any>(funcName: string, data: In): Promise<Out>;
 }
 export declare class PikkuRPCService<Services extends CoreServices, TypedRPC = PikkuRPC> {
-    getContextRPCService(services: Services, wire: PikkuWire, requiresAuth?: boolean | undefined, depth?: number): TypedRPC;
+    getContextRPCService(services: Services, wire: PikkuWire, requiresAuthOrOptions?: boolean | {
+        requiresAuth?: boolean;
+        sessionService?: SessionService<CoreUserSession>;
+    } | undefined, depth?: number): TypedRPC;
 }
-export declare const rpcService: PikkuRPCService<import("../../types/core.types.js").CoreSingletonServices<{
-    logLevel?: import("../../index.js").LogLevel;
+export declare const rpcService: PikkuRPCService<CoreSingletonServices<{
+    logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
 }>, PikkuRPC>;