@pikku/core 0.11.1 → 0.12.0

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

@@ -2,8 +2,8 @@ import { getErrorResponse } from '../../errors/error-handler.js';
 import { closeWireServices } from '../../utils.js';
 import { pikkuState } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
-import { BadRequestError, NotFoundError } from '../../errors/errors.js';
-import { PikkuSessionService } from '../../services/user-session-service.js';
+import { BadRequestError, NotFoundError, PikkuMissingMetaError, } from '../../errors/errors.js';
+import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
 export class MCPError extends Error {
     error;
     constructor(error) {
@@ -14,39 +14,26 @@ export class MCPError extends Error {
     }
 }
 export const wireMCPResource = (mcpResource) => {
-    const resourcesMeta = pikkuState('mcp', 'resourcesMeta');
+    const resourcesMeta = pikkuState(null, 'mcp', 'resourcesMeta');
     const mcpResourceMeta = resourcesMeta[mcpResource.uri];
     if (!mcpResourceMeta) {
-        throw new Error(`MCP resource metadata not found for '${mcpResource.uri}'`);
+        throw new PikkuMissingMetaError(`Missing generated metadata for MCP resource '${mcpResource.uri}'`);
     }
-    addFunction(mcpResourceMeta.pikkuFuncName, mcpResource.func);
-    const resources = pikkuState('mcp', 'resources');
+    addFunction(mcpResourceMeta.pikkuFuncId, mcpResource.func);
+    const resources = pikkuState(null, 'mcp', 'resources');
     if (resources.has(mcpResource.uri)) {
         throw new Error(`MCP resource already exists: ${mcpResource.uri}`);
     }
     resources.set(mcpResource.uri, mcpResource);
 };
-export const wireMCPTool = (mcpTool) => {
-    const toolsMeta = pikkuState('mcp', 'toolsMeta');
-    const mcpToolMeta = toolsMeta[mcpTool.name];
-    if (!mcpToolMeta) {
-        throw new Error(`MCP tool metadata not found for '${mcpTool.name}'`);
-    }
-    addFunction(mcpToolMeta.pikkuFuncName, mcpTool.func);
-    const tools = pikkuState('mcp', 'tools');
-    if (tools.has(mcpTool.name)) {
-        throw new Error(`MCP tool already exists: ${mcpTool.name}`);
-    }
-    tools.set(mcpTool.name, mcpTool);
-};
 export const wireMCPPrompt = (mcpPrompt) => {
-    const promptsMeta = pikkuState('mcp', 'promptsMeta');
+    const promptsMeta = pikkuState(null, 'mcp', 'promptsMeta');
     const mcpPromptMeta = promptsMeta[mcpPrompt.name];
     if (!mcpPromptMeta) {
-        throw new Error(`MCP prompt metadata not found for '${mcpPrompt.name}'`);
+        throw new PikkuMissingMetaError(`Missing generated metadata for MCP prompt '${mcpPrompt.name}'`);
     }
-    addFunction(mcpPromptMeta.pikkuFuncName, mcpPrompt.func);
-    const prompts = pikkuState('mcp', 'prompts');
+    addFunction(mcpPromptMeta.pikkuFuncId, mcpPrompt.func);
+    const prompts = pikkuState(null, 'mcp', 'prompts');
     if (prompts.has(mcpPrompt.name)) {
         throw new Error(`MCP prompt already exists: ${mcpPrompt.name}`);
     }
@@ -54,13 +41,13 @@ export const wireMCPPrompt = (mcpPrompt) => {
 };
 export async function runMCPResource(request, params, uri) {
     let endpoint;
-    let pikkuFuncName;
+    let pikkuFuncId;
     let extractedParams = {};
-    const metas = pikkuState('mcp', 'resourcesMeta');
-    const endpoints = pikkuState('mcp', 'resources');
+    const metas = pikkuState(null, 'mcp', 'resourcesMeta');
+    const endpoints = pikkuState(null, 'mcp', 'resources');
     if (endpoints.has(uri)) {
         endpoint = endpoints.get(uri);
-        pikkuFuncName = metas[uri]?.pikkuFuncName;
+        pikkuFuncId = metas[uri]?.pikkuFuncId;
     }
     else {
         for (const [uriTemplate, value] of endpoints.entries()) {
@@ -72,7 +59,7 @@ export async function runMCPResource(request, params, uri) {
             const match = uri.match(regex);
             if (match) {
                 endpoint = value;
-                pikkuFuncName = metas[uriTemplate]?.pikkuFuncName;
+                pikkuFuncId = metas[uriTemplate]?.pikkuFuncId;
                 // Extract parameter values and create params object
                 for (let i = 0; i < paramNames.length; i++) {
                     extractedParams[paramNames[i]] = match[i + 1]; // match[0] is the full match
@@ -84,61 +71,63 @@ export async function runMCPResource(request, params, uri) {
     return await runMCPPikkuFunc({
         ...request,
         params: { ...request.params, ...extractedParams },
-    }, 'resource', uri, endpoint, pikkuFuncName, { ...params, mcp: { ...params.mcp, uri } });
+    }, 'resource', uri, endpoint, pikkuFuncId, { ...params, mcp: { ...params.mcp, uri } });
 }
 export async function runMCPTool(request, params, name) {
-    const endpoint = pikkuState('mcp', 'tools').get(name);
-    const meta = pikkuState('mcp', 'toolsMeta')[name];
-    return await runMCPPikkuFunc(request, 'tool', name, endpoint, meta?.pikkuFuncName, params);
+    const meta = pikkuState(null, 'mcp', 'toolsMeta')[name];
+    return await runMCPPikkuFunc(request, 'tool', name, undefined, meta?.pikkuFuncId, params);
 }
 export async function runMCPPrompt(request, params, name) {
-    const endpoint = pikkuState('mcp', 'prompts').get(name);
-    const meta = pikkuState('mcp', 'promptsMeta')[name];
-    return await runMCPPikkuFunc(request, 'prompt', name, endpoint, meta?.pikkuFuncName, params);
+    const endpoint = pikkuState(null, 'mcp', 'prompts').get(name);
+    const meta = pikkuState(null, 'mcp', 'promptsMeta')[name];
+    return await runMCPPikkuFunc(request, 'prompt', name, endpoint, meta?.pikkuFuncId, params);
 }
 /**
  * JSON-RPC 2.0 compatible MCP endpoint runner
  */
-async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncName, { singletonServices, createWireServices, mcp: mcpWire }) {
+async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncId, { singletonServices, createWireServices, mcp: mcpWire }) {
     let wireServices;
     try {
-        // Validate JSON-RPC request structure
         if (request.jsonrpc !== '2.0') {
             throw new BadRequestError('Invalid JSON-RPC version, only supoorted version is 2.0');
         }
-        if (!mcp) {
+        if (mcp === undefined && type !== 'tool') {
             throw new NotFoundError(`MCP '${type}' registration not found for '${name}'`);
         }
-        if (!pikkuFuncName) {
+        if (!pikkuFuncId) {
             throw new NotFoundError(`MCP '${type}' PikkuFunction Mapping not found for '${name}'`);
         }
         singletonServices.logger.debug(`Running MCP ${type}: ${name}`);
+        const mcpSessionService = new PikkuSessionService();
         const wire = {
             mcp: mcpWire,
-            session: new PikkuSessionService(),
+            ...createMiddlewareSessionWireProps(mcpSessionService),
         };
-        // Get metadata for the MCP endpoint to access pre-resolved middleware
         let meta;
         if (type === 'resource') {
-            meta = pikkuState('mcp', 'resourcesMeta')[name];
+            meta = pikkuState(null, 'mcp', 'resourcesMeta')[name];
         }
         else if (type === 'tool') {
-            meta = pikkuState('mcp', 'toolsMeta')[name];
+            meta = pikkuState(null, 'mcp', 'toolsMeta')[name];
         }
         else if (type === 'prompt') {
-            meta = pikkuState('mcp', 'promptsMeta')[name];
+            meta = pikkuState(null, 'mcp', 'promptsMeta')[name];
         }
-        const result = await runPikkuFunc('mcp', `${type}:${name}`, pikkuFuncName, {
+        let result = await runPikkuFunc('mcp', `${type}:${name}`, pikkuFuncId, {
             singletonServices,
             createWireServices,
             data: () => request.params,
             inheritedMiddleware: meta?.middleware,
-            wireMiddleware: mcp.middleware,
+            wireMiddleware: mcp?.middleware,
             inheritedPermissions: meta?.permissions,
-            wirePermissions: mcp.permissions,
-            tags: mcp.tags,
+            wirePermissions: mcp?.permissions,
+            tags: mcp?.tags,
             wire,
+            sessionService: mcpSessionService,
         });
+        if (type === 'tool' && meta?.outputSchema !== 'MCPToolResponse') {
+            result = [{ type: 'text', text: JSON.stringify(result) }];
+        }
         return {
             id: request.id,
             result,
@@ -172,21 +161,18 @@ async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncName, { single
         }
     }
 }
-export const getMCPTools = () => {
-    return pikkuState('mcp', 'tools');
-};
 export const getMCPResources = () => {
-    return pikkuState('mcp', 'resources');
+    return pikkuState(null, 'mcp', 'resources');
 };
 export const getMCPResourcesMeta = () => {
-    return pikkuState('mcp', 'resourcesMeta');
+    return pikkuState(null, 'mcp', 'resourcesMeta');
 };
 export const getMCPToolsMeta = () => {
-    return pikkuState('mcp', 'toolsMeta');
+    return pikkuState(null, 'mcp', 'toolsMeta');
 };
 export const getMCPPrompts = () => {
-    return pikkuState('mcp', 'prompts');
+    return pikkuState(null, 'mcp', 'prompts');
 };
 export const getMCPPromptsMeta = () => {
-    return pikkuState('mcp', 'promptsMeta');
+    return pikkuState(null, 'mcp', 'promptsMeta');
 };

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

@@ -26,7 +26,7 @@ export type PikkuMCP<Tools extends string = any> = {
  * Represents metadata for MCP resources, including name, description, and documentation.
  */
 export type MCPResourceMeta = Record<string, Omit<CoreMCPResource, 'func' | 'middleware' | 'permissions'> & {
-    pikkuFuncName: string;
+    pikkuFuncId: string;
     inputSchema: string | null;
     outputSchema: string | null;
     middleware?: MiddlewareMetadata[];
@@ -36,7 +36,7 @@ export type MCPResourceMeta = Record<string, Omit<CoreMCPResource, 'func' | 'mid
  * Represents metadata for MCP tools, including name, description, and documentation.
  */
 export type MCPToolMeta = Record<string, Omit<CoreMCPTool, 'func' | 'middleware' | 'permissions'> & {
-    pikkuFuncName: string;
+    pikkuFuncId: string;
     inputSchema: string | null;
     outputSchema: string | null;
     middleware?: MiddlewareMetadata[];
@@ -46,7 +46,7 @@ export type MCPToolMeta = Record<string, Omit<CoreMCPTool, 'func' | 'middleware'
  * Represents metadata for MCP prompts, including name, description, and arguments.
  */
 export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middleware' | 'permissions'> & {
-    pikkuFuncName: string;
+    pikkuFuncId: string;
     inputSchema: string | null;
     outputSchema: string | null;
     arguments: Array<{

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

@@ -0,0 +1,2 @@
+export type { CoreNodeConfig, NodeType } from './node.types.js';
+export type { NodesMeta } from './node.types.js';

package/dist/wirings/node/index.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,20 @@
+export type NodeType = 'trigger' | 'action' | 'end';
+export type CoreNodeConfig = {
+    displayName: string;
+    category: string;
+    type: NodeType;
+    errorOutput?: boolean;
+};
+export type NodeMeta = {
+    name: string;
+    displayName: string;
+    category: string;
+    type: NodeType;
+    rpc: string;
+    description?: string;
+    errorOutput: boolean;
+    inputSchemaName: string | null;
+    outputSchemaName: string | null;
+    tags?: string[];
+};
+export type NodesMeta = Record<string, NodeMeta>;

package/dist/wirings/node/node.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,3 @@
+export { OAuth2Client } from './oauth2-client.js';
+export { wireOAuth2Credential } from './wire-oauth2-credential.js';
+export type { OAuth2AppCredential, OAuth2Token } from './oauth2.types.js';

package/dist/wirings/oauth2/index.js

@@ -0,0 +1,2 @@
+export { OAuth2Client } from './oauth2-client.js';
+export { wireOAuth2Credential } from './wire-oauth2-credential.js';

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;