@ductape/sdk 0.1.8 → 0.1.9

package/dist/apps/utils/credential-manager.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * CredentialManager - Manages shared credentials for action execution
+ *
+ * This utility allows developers to set up credentials once per app/product/env
+ * combination, and have those credentials automatically merged into action
+ * inputs before resolution.
+ *
+ * @example
+ * ```ts
+ * // Set up shared credentials once
+ * ductape.api.config({
+ *   product: 'my-product',
+ *   app: 'stripe',
+ *   env: 'prd',
+ *   credentials: {
+ *     'headers:Authorization': '$Secret{StripeApiKey}',
+ *   }
+ * });
+ *
+ * // Now all stripe actions in prd env automatically include credentials
+ * const result = await ductape.api.run({
+ *   product: 'my-product',
+ *   app: 'stripe',
+ *   env: 'prd',
+ *   event: 'create-charge',
+ *   input: { amount: 1000, currency: 'usd' }
+ * });
+ * // Input automatically includes 'headers:Authorization' from shared credentials
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.credentialManager = exports.CredentialManager = exports.CredentialError = void 0;
+/**
+ * Validation error thrown for invalid credential configurations
+ */
+class CredentialError extends Error {
+    constructor(message, errorType) {
+        super(message);
+        this.errorType = errorType;
+        this.name = 'CredentialError';
+    }
+}
+exports.CredentialError = CredentialError;
+/**
+ * Generate a unique key for product/app/env combination
+ */
+function generateCredentialKey(product, app, env) {
+    return `${product}:${app}:${env}`;
+}
+/**
+ * CredentialManager stores and retrieves shared credentials
+ * for product/app/env combinations.
+ */
+class CredentialManager {
+    constructor() {
+        /** Storage for credentials, keyed by product:app:env */
+        this.credentials = new Map();
+    }
+    /**
+     * Share credentials for a product/app/env combination
+     *
+     * @param config - Credential configuration
+     * @throws CredentialError if configuration is invalid
+     */
+    share(config) {
+        // Validate required fields
+        if (!config.product || typeof config.product !== 'string') {
+            throw new CredentialError('Shared credentials require a valid product tag', 'invalid_config');
+        }
+        if (!config.app || typeof config.app !== 'string') {
+            throw new CredentialError('Shared credentials require a valid app tag', 'invalid_config');
+        }
+        if (!config.env || typeof config.env !== 'string') {
+            throw new CredentialError('Shared credentials require a valid env slug', 'invalid_config');
+        }
+        // Ensure credentials are provided
+        if (!config.credentials || typeof config.credentials !== 'object') {
+            throw new CredentialError('Shared credentials require a credentials object', 'invalid_config');
+        }
+        if (Object.keys(config.credentials).length === 0) {
+            throw new CredentialError('Shared credentials object cannot be empty', 'invalid_config');
+        }
+        // Validate credential values are not undefined
+        for (const [key, value] of Object.entries(config.credentials)) {
+            if (value === undefined) {
+                throw new CredentialError(`Credential "${key}" cannot be undefined. Provide a valid value or remove the key.`, 'invalid_config');
+            }
+        }
+        const key = generateCredentialKey(config.product, config.app, config.env);
+        this.credentials.set(key, Object.assign({}, config.credentials));
+    }
+    /**
+     * Get shared credentials for a product/app/env combination
+     *
+     * @param options - Options specifying product, app, and env
+     * @returns Shared credentials or undefined if not set
+     */
+    get(options) {
+        const key = generateCredentialKey(options.product, options.app, options.env);
+        return this.credentials.get(key);
+    }
+    /**
+     * Check if shared credentials exist for a product/app/env combination
+     */
+    has(options) {
+        return this.get(options) !== undefined;
+    }
+    /**
+     * Remove shared credentials for a product/app/env combination
+     *
+     * @param options - Options specifying product, app, and env
+     * @returns true if credentials were removed, false if they didn't exist
+     */
+    remove(options) {
+        const key = generateCredentialKey(options.product, options.app, options.env);
+        return this.credentials.delete(key);
+    }
+    /**
+     * Clear all shared credentials
+     */
+    clearAll() {
+        this.credentials.clear();
+    }
+    /**
+     * Clear all credentials for a specific product
+     */
+    clearProduct(product) {
+        const keysToDelete = [];
+        for (const key of this.credentials.keys()) {
+            if (key.startsWith(`${product}:`)) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            this.credentials.delete(key);
+        }
+    }
+    /**
+     * Clear all credentials for a specific app (across all products)
+     */
+    clearApp(app) {
+        const keysToDelete = [];
+        for (const key of this.credentials.keys()) {
+            // Key format: product:app:env
+            const parts = key.split(':');
+            if (parts[1] === app) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            this.credentials.delete(key);
+        }
+    }
+    /**
+     * Clear all credentials for a specific environment (across all products and apps)
+     */
+    clearEnv(env) {
+        const keysToDelete = [];
+        for (const key of this.credentials.keys()) {
+            // Key format: product:app:env
+            if (key.endsWith(`:${env}`)) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            this.credentials.delete(key);
+        }
+    }
+    /**
+     * Get all registered product/app/env combinations
+     */
+    list() {
+        const result = [];
+        for (const key of this.credentials.keys()) {
+            const parts = key.split(':');
+            result.push({ product: parts[0], app: parts[1], env: parts[2] });
+        }
+        return result;
+    }
+    /**
+     * Merge shared credentials with user-provided input
+     * Shared credentials are used as defaults; user input takes precedence
+     *
+     * @param sharedCredentials - Shared credentials from manager
+     * @param userInput - User-provided flat input
+     * @returns Merged input with shared credentials as defaults
+     */
+    mergeWithInput(sharedCredentials, userInput) {
+        // Shared credentials come first (lower priority), user input overwrites
+        return Object.assign(Object.assign({}, sharedCredentials), userInput);
+    }
+}
+exports.CredentialManager = CredentialManager;
+/**
+ * Singleton instance for convenience
+ */
+exports.credentialManager = new CredentialManager();
+//# sourceMappingURL=credential-manager.js.map

package/dist/apps/utils/credential-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-manager.js","sourceRoot":"","sources":["../../../src/apps/utils/credential-manager.ts"],"names":[],"mappings":"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"}

package/dist/apps/utils/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Apps utility exports
+ */
+export { InputResolver, inputResolver, resolveInput, InputResolutionError, LOCATION_PREFIXES, type InputLocation, type ILocationMap, type IResolvedInput, type IResolveOptions, } from './input-resolver';
+export { AuthContextManager, authContextManager, AuthContextError, type IAuthContextConfig, } from './auth-context-manager';
+export { CredentialManager, credentialManager, CredentialError, type IShareCredentialsConfig, type IGetCredentialsOptions, } from './credential-manager';
+export { OAuthManager, oauthManager, OAuthError, type IOAuthTokens, type IOAuthRefreshResult, type IOAuthConfig, type CredentialsBuilder, } from './oauth-manager';
+export { isStructuredInput, hasPrefixedKeys, processActionInput, createFlatInputValidator, getInputKeySummary, type IProcessInputOptions, } from './input-helpers';
+export * from './string.utils';
+export * from './objects.utils';

package/dist/apps/utils/index.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Apps utility exports
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInputKeySummary = exports.createFlatInputValidator = exports.processActionInput = exports.hasPrefixedKeys = exports.isStructuredInput = exports.OAuthError = exports.oauthManager = exports.OAuthManager = exports.CredentialError = exports.credentialManager = exports.CredentialManager = exports.AuthContextError = exports.authContextManager = exports.AuthContextManager = exports.LOCATION_PREFIXES = exports.InputResolutionError = exports.resolveInput = exports.inputResolver = exports.InputResolver = void 0;
+// Input resolution utilities
+var input_resolver_1 = require("./input-resolver");
+Object.defineProperty(exports, "InputResolver", { enumerable: true, get: function () { return input_resolver_1.InputResolver; } });
+Object.defineProperty(exports, "inputResolver", { enumerable: true, get: function () { return input_resolver_1.inputResolver; } });
+Object.defineProperty(exports, "resolveInput", { enumerable: true, get: function () { return input_resolver_1.resolveInput; } });
+Object.defineProperty(exports, "InputResolutionError", { enumerable: true, get: function () { return input_resolver_1.InputResolutionError; } });
+Object.defineProperty(exports, "LOCATION_PREFIXES", { enumerable: true, get: function () { return input_resolver_1.LOCATION_PREFIXES; } });
+// Auth context management
+var auth_context_manager_1 = require("./auth-context-manager");
+Object.defineProperty(exports, "AuthContextManager", { enumerable: true, get: function () { return auth_context_manager_1.AuthContextManager; } });
+Object.defineProperty(exports, "authContextManager", { enumerable: true, get: function () { return auth_context_manager_1.authContextManager; } });
+Object.defineProperty(exports, "AuthContextError", { enumerable: true, get: function () { return auth_context_manager_1.AuthContextError; } });
+// Credential management for shared credentials
+var credential_manager_1 = require("./credential-manager");
+Object.defineProperty(exports, "CredentialManager", { enumerable: true, get: function () { return credential_manager_1.CredentialManager; } });
+Object.defineProperty(exports, "credentialManager", { enumerable: true, get: function () { return credential_manager_1.credentialManager; } });
+Object.defineProperty(exports, "CredentialError", { enumerable: true, get: function () { return credential_manager_1.CredentialError; } });
+// OAuth management with automatic refresh and $Secret{} integration
+var oauth_manager_1 = require("./oauth-manager");
+Object.defineProperty(exports, "OAuthManager", { enumerable: true, get: function () { return oauth_manager_1.OAuthManager; } });
+Object.defineProperty(exports, "oauthManager", { enumerable: true, get: function () { return oauth_manager_1.oauthManager; } });
+Object.defineProperty(exports, "OAuthError", { enumerable: true, get: function () { return oauth_manager_1.OAuthError; } });
+// Input helpers for detection and processing
+var input_helpers_1 = require("./input-helpers");
+Object.defineProperty(exports, "isStructuredInput", { enumerable: true, get: function () { return input_helpers_1.isStructuredInput; } });
+Object.defineProperty(exports, "hasPrefixedKeys", { enumerable: true, get: function () { return input_helpers_1.hasPrefixedKeys; } });
+Object.defineProperty(exports, "processActionInput", { enumerable: true, get: function () { return input_helpers_1.processActionInput; } });
+Object.defineProperty(exports, "createFlatInputValidator", { enumerable: true, get: function () { return input_helpers_1.createFlatInputValidator; } });
+Object.defineProperty(exports, "getInputKeySummary", { enumerable: true, get: function () { return input_helpers_1.getInputKeySummary; } });
+// String utilities
+__exportStar(require("./string.utils"), exports);
+// Object utilities
+__exportStar(require("./objects.utils"), exports);
+//# sourceMappingURL=index.js.map

package/dist/apps/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/apps/utils/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;AAEH,6BAA6B;AAC7B,mDAU0B;AATxB,+GAAA,aAAa,OAAA;AACb,+GAAA,aAAa,OAAA;AACb,8GAAA,YAAY,OAAA;AACZ,sHAAA,oBAAoB,OAAA;AACpB,mHAAA,iBAAiB,OAAA;AAOnB,0BAA0B;AAC1B,+DAKgC;AAJ9B,0HAAA,kBAAkB,OAAA;AAClB,0HAAA,kBAAkB,OAAA;AAClB,wHAAA,gBAAgB,OAAA;AAIlB,+CAA+C;AAC/C,2DAM8B;AAL5B,uHAAA,iBAAiB,OAAA;AACjB,uHAAA,iBAAiB,OAAA;AACjB,qHAAA,eAAe,OAAA;AAKjB,oEAAoE;AACpE,iDAQyB;AAPvB,6GAAA,YAAY,OAAA;AACZ,6GAAA,YAAY,OAAA;AACZ,2GAAA,UAAU,OAAA;AAOZ,6CAA6C;AAC7C,iDAOyB;AANvB,kHAAA,iBAAiB,OAAA;AACjB,gHAAA,eAAe,OAAA;AACf,mHAAA,kBAAkB,OAAA;AAClB,yHAAA,wBAAwB,OAAA;AACxB,mHAAA,kBAAkB,OAAA;AAIpB,mBAAmB;AACnB,iDAA+B;AAE/B,mBAAmB;AACnB,kDAAgC"}

package/dist/apps/utils/input-helpers.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Input Helpers - Utilities for detecting and processing action inputs
+ */
+import { IActionRequest, IAppAction } from '../../types';
+import { IResolveOptions } from './input-resolver';
+import { AuthContextManager } from './auth-context-manager';
+/**
+ * Check if the input appears to be a structured IActionRequest format
+ *
+ * Structured format has ONLY these keys: body, params, query, headers, input
+ * Flat format has arbitrary keys that need to be resolved
+ *
+ * @param input - Input to check
+ * @returns true if structured, false if flat
+ */
+export declare function isStructuredInput(input: Record<string, unknown>): boolean;
+/**
+ * Check if input contains any flat-style prefixed keys
+ *
+ * @param input - Input to check
+ * @returns true if contains prefixed keys like 'body:key', 'params:id'
+ */
+export declare function hasPrefixedKeys(input: Record<string, unknown>): boolean;
+/**
+ * Options for processing action input
+ */
+export interface IProcessInputOptions extends IResolveOptions {
+    /** Skip validation after resolution */
+    skipValidation?: boolean;
+}
+/**
+ * Process action input - detect format and resolve if flat
+ *
+ * This is the main entry point for action input processing:
+ * 1. Detects if input is structured or flat
+ * 2. If flat, resolves it using the action schema
+ * 3. Merges auth context if provided
+ * 4. Optionally validates required fields
+ *
+ * @param input - Raw input (structured or flat)
+ * @param action - Action schema for resolution
+ * @param authManager - Optional auth context manager
+ * @param app - App tag for auth context lookup
+ * @param env - Env slug for auth context lookup
+ * @param product - Optional product tag for auth context lookup
+ * @param options - Processing options
+ * @returns Structured IActionRequest ready for execution
+ * @throws InputResolutionError for invalid inputs in strict mode
+ */
+export declare function processActionInput(input: Record<string, unknown>, action: IAppAction, authManager?: AuthContextManager, app?: string, env?: string, product?: string, options?: IProcessInputOptions): IActionRequest;
+/**
+ * Create a flat input validator for an action
+ *
+ * Returns a function that validates flat input against the action schema
+ * without actually resolving it. Useful for pre-validation.
+ *
+ * @param action - Action schema
+ * @returns Validator function
+ */
+export declare function createFlatInputValidator(action: IAppAction): (input: Record<string, unknown>) => void;
+/**
+ * Get a user-friendly summary of valid input keys for an action
+ *
+ * @param action - Action schema
+ * @returns Human-readable summary string
+ */
+export declare function getInputKeySummary(action: IAppAction): string;

package/dist/apps/utils/input-helpers.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * Input Helpers - Utilities for detecting and processing action inputs
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStructuredInput = isStructuredInput;
+exports.hasPrefixedKeys = hasPrefixedKeys;
+exports.processActionInput = processActionInput;
+exports.createFlatInputValidator = createFlatInputValidator;
+exports.getInputKeySummary = getInputKeySummary;
+const input_resolver_1 = require("./input-resolver");
+/**
+ * Valid top-level keys for structured IActionRequest
+ */
+const STRUCTURED_KEYS = new Set(['body', 'params', 'query', 'headers', 'input']);
+/**
+ * Check if the input appears to be a structured IActionRequest format
+ *
+ * Structured format has ONLY these keys: body, params, query, headers, input
+ * Flat format has arbitrary keys that need to be resolved
+ *
+ * @param input - Input to check
+ * @returns true if structured, false if flat
+ */
+function isStructuredInput(input) {
+    if (!input || typeof input !== 'object') {
+        return false;
+    }
+    const keys = Object.keys(input);
+    // Empty object is considered flat (will be resolved to empty structured)
+    if (keys.length === 0) {
+        return false;
+    }
+    // Check if ALL keys are structured keys
+    // If any key is NOT a structured key, it's flat input
+    for (const key of keys) {
+        if (!STRUCTURED_KEYS.has(key)) {
+            return false;
+        }
+    }
+    // Additional check: if it has structured keys, the values should be objects
+    for (const key of keys) {
+        const value = input[key];
+        // For structured input, body/params/query/headers should be objects or undefined
+        if (key !== 'input' && value !== undefined && value !== null) {
+            if (typeof value !== 'object' || Array.isArray(value)) {
+                // If a structured key has a non-object value, treat as flat input
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Check if input contains any flat-style prefixed keys
+ *
+ * @param input - Input to check
+ * @returns true if contains prefixed keys like 'body:key', 'params:id'
+ */
+function hasPrefixedKeys(input) {
+    const prefixes = ['body:', 'params:', 'query:', 'headers:'];
+    for (const key of Object.keys(input)) {
+        for (const prefix of prefixes) {
+            if (key.startsWith(prefix)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Process action input - detect format and resolve if flat
+ *
+ * This is the main entry point for action input processing:
+ * 1. Detects if input is structured or flat
+ * 2. If flat, resolves it using the action schema
+ * 3. Merges auth context if provided
+ * 4. Optionally validates required fields
+ *
+ * @param input - Raw input (structured or flat)
+ * @param action - Action schema for resolution
+ * @param authManager - Optional auth context manager
+ * @param app - App tag for auth context lookup
+ * @param env - Env slug for auth context lookup
+ * @param product - Optional product tag for auth context lookup
+ * @param options - Processing options
+ * @returns Structured IActionRequest ready for execution
+ * @throws InputResolutionError for invalid inputs in strict mode
+ */
+function processActionInput(input, action, authManager, app, env, product, options = {}) {
+    const { strict = true, skipValidation = false } = options;
+    const resolver = new input_resolver_1.InputResolver();
+    // Get auth context if available
+    let authContext;
+    if (authManager && app && env) {
+        authContext = authManager.getAuth(app, env, product);
+    }
+    let resolved;
+    if (isStructuredInput(input)) {
+        // Already structured - merge with auth context
+        resolved = input;
+        if (authContext) {
+            resolved = authManager.mergeWithInput(authContext, resolved);
+        }
+    }
+    else {
+        // Flat input - resolve using action schema
+        resolved = resolver.resolve(input, action, {
+            strict,
+            authContext,
+            defaultLocation: 'body',
+        });
+    }
+    // Validate required fields if not skipped
+    if (!skipValidation && strict) {
+        resolver.validateRequired(resolved, action);
+    }
+    // Convert to IActionRequest format
+    return {
+        body: resolved.body,
+        params: resolved.params,
+        query: resolved.query,
+        headers: resolved.headers,
+    };
+}
+/**
+ * Create a flat input validator for an action
+ *
+ * Returns a function that validates flat input against the action schema
+ * without actually resolving it. Useful for pre-validation.
+ *
+ * @param action - Action schema
+ * @returns Validator function
+ */
+function createFlatInputValidator(action) {
+    const resolver = new input_resolver_1.InputResolver();
+    const locationMap = resolver.buildLocationMap(action);
+    return (input) => {
+        for (const key of Object.keys(input)) {
+            const [explicitLocation, actualKey] = resolver.parseKey(key);
+            if (explicitLocation) {
+                // Check prefixed key exists in the specified location
+                const locationsForKey = locationMap.keyToLocations.get(actualKey);
+                if (!locationsForKey || !locationsForKey.includes(explicitLocation)) {
+                    throw new input_resolver_1.InputResolutionError(`Key '${actualKey}' does not exist in '${explicitLocation}' for action '${action.tag}'`, key, 'unknown_key');
+                }
+            }
+            else {
+                // Check non-prefixed key exists in schema
+                const locations = locationMap.keyToLocations.get(actualKey);
+                if (!locations || locations.length === 0) {
+                    throw new input_resolver_1.InputResolutionError(`Unknown key '${actualKey}' for action '${action.tag}'`, actualKey, 'unknown_key');
+                }
+                if (locations.length > 1) {
+                    throw new input_resolver_1.InputResolutionError(`Ambiguous key '${actualKey}' exists in: ${locations.join(', ')}. Use a prefix.`, actualKey, 'conflict');
+                }
+            }
+        }
+    };
+}
+/**
+ * Get a user-friendly summary of valid input keys for an action
+ *
+ * @param action - Action schema
+ * @returns Human-readable summary string
+ */
+function getInputKeySummary(action) {
+    const resolver = new input_resolver_1.InputResolver();
+    const validKeys = resolver.getValidKeys(action);
+    const conflictingKeys = resolver.getConflictingKeys(action);
+    const lines = [];
+    lines.push(`Valid input keys for action '${action.tag}':`);
+    lines.push('');
+    for (const { key, locations } of validKeys) {
+        const isConflict = conflictingKeys.some((c) => c.key === key);
+        if (isConflict) {
+            lines.push(`  ${key} (conflict - use prefix: ${locations.map((l) => `'${l}:${key}'`).join(' or ')})`);
+        }
+        else {
+            lines.push(`  ${key} -> ${locations[0]}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=input-helpers.js.map

package/dist/apps/utils/input-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-helpers.js","sourceRoot":"","sources":["../../../src/apps/utils/input-helpers.ts"],"names":[],"mappings":"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"}