@ductape/sdk 0.1.7 → 0.1.9

package/dist/index.d.ts

@@ -15,6 +15,7 @@ import { IOAuthConfig } from './apps/utils/oauth-manager';
 import { JobsService, JobStatus, IJobListOptions, ICancelOptions, IRetryOptions, IRescheduleOptions, IJobWebhookConfig } from './jobs';
 import { SecretsService, ICreateSecretInput, IUpdateSecretInput, ISecretMetadata, ISecret, IResolveSecretsOptions } from './secrets';
 import { IWarehouseQuery, IDataSource } from './warehouse';
+import { CloudService, ICreateCloudConnectionInput, ICloudConnectionSetup, ICloudConnection, ICompleteCloudConnectionInput, IValidateCloudConnectionResult, IListCloudResourcesInput, IListCloudResourcesResult, IImportCloudResourceInput, IImportCloudResourceResult, IProvisionCloudResourceInput, IProvisionCloudResourceResult, ICloudRuntimeCredentialsInput, ICloudRuntimeCredentials } from './cloud';
 /**
  * @typedef {Object} IProduct
  * @property {string} tag - Unique product tag.
@@ -254,6 +255,8 @@ export type { IAdapterConnectionOptions as IVectorAdapterConnectionOptions, IVec
 export { SecretsService } from './secrets';
 export { SECRET_PATTERN, SECRET_PATTERN_GLOBAL, SecretNotFoundError, SecretScopeError, SecretEnvironmentError, SecretExpiredError, SecretRevokedError, SecretResolutionError, isSecretReference, containsSecretReferences, extractSecretKeys, findAllSecretReferences, mightContainSecrets, } from './secrets';
 export type { SecretTokenType, ICreateSecretInput, IUpdateSecretInput, ISecretMetadata, ISecret, ISecretCheck, IResolveSecretsOptions, ISecretResolutionResult, ISecretsServiceConfig, ISecretsService, } from './secrets';
+export { CloudService, CloudError } from './cloud';
+export type { CloudProvider, CloudAuthMode, CloudConnectionStatus, CloudConnectionScope, ICloudConnection, ICreateCloudConnectionInput, ICloudConnectionSetup, ICompleteCloudConnectionInput, IValidateCloudConnectionResult, CloudResourceService, ICloudResource, IListCloudResourcesInput, IListCloudResourcesResult, CloudComponentType, IImportCloudResourceInput, IProvisionCloudResourceInput, ICloudComponentDraft, IImportCloudResourceResult, IProvisionCloudResourceResult, ICloudRuntimeCredentialsInput, ICloudRuntimeCredentials, ComponentCloudAuthMode, ICloudLinkedComponentFields, } from './cloud';
 export interface IDuctape {
 }
 export default class Ductape implements IDuctape {
@@ -281,6 +284,7 @@ export default class Ductape implements IDuctape {
     private _cacheService;
     private _jobsService;
     private _secretsService;
+    private _cloudService;
     private _privateKey;
     private _quotaService;
     private _fallbackService;
@@ -290,6 +294,9 @@ export default class Ductape implements IDuctape {
     private importService;
     private environment;
     private redis_url;
+    /** Inherited by connect/query payloads when product/env omitted */
+    private defaultProduct?;
+    private defaultEnv?;
     private redisClient?;
     private jobsQueue;
     private healthCheckQueue;
@@ -303,7 +310,7 @@ export default class Ductape implements IDuctape {
      * This is separate from monitor() which sets up job queues
      */
     private connectCacheRedis;
-    constructor({ accessKey, env_type, redis_url }: IDuctapeInit);
+    constructor({ accessKey, redis_url, product, env, local }: IDuctapeInit);
     private loadBullMQ;
     /**
      * Connects to Redis and initializes job and health check queues and workers.
@@ -332,6 +339,9 @@ export default class Ductape implements IDuctape {
      * @param {string} public_key - The public key.
      */
     setPublicKey(public_key: string): void;
+    private runtimeDefaultsForServices;
+    /** Merge constructor product/env into call options (sessions, storage, cache, notifications, resilience, etc.). */
+    private mergeRuntime;
     private getProductBuilder;
     private getAppBuilder;
     private initProductBuilder;
@@ -3352,6 +3362,38 @@ export default class Ductape implements IDuctape {
          */
         getService: () => Promise<SecretsService>;
     };
+    /**
+     * Cloud provider connections (AWS, GCP, Azure) for discovering, importing, and provisioning resources.
+     *
+     * @example
+     * const setup = await ductape.cloud.connections.create({
+     *   provider: 'aws',
+     *   name: 'Production AWS',
+     *   scopes: ['storage', 'broker'],
+     * });
+     * await ductape.cloud.connections.complete(setup.connection.id, { role_arn: 'arn:aws:iam::123:role/Ductape' });
+     */
+    cloud: {
+        connections: {
+            create: (input: ICreateCloudConnectionInput) => Promise<ICloudConnectionSetup>;
+            list: () => Promise<ICloudConnection[]>;
+            fetch: (connectionId: string) => Promise<ICloudConnection>;
+            delete: (connectionId: string) => Promise<void>;
+            complete: (connectionId: string, input: ICompleteCloudConnectionInput) => Promise<ICloudConnection>;
+            validate: (connectionId: string) => Promise<IValidateCloudConnectionResult>;
+        };
+        resources: {
+            list: (input: IListCloudResourcesInput) => Promise<IListCloudResourcesResult>;
+            import: (input: IImportCloudResourceInput) => Promise<IImportCloudResourceResult>;
+            importAndPersist: (input: IImportCloudResourceInput) => Promise<IImportCloudResourceResult>;
+            provision: (input: IProvisionCloudResourceInput) => Promise<IProvisionCloudResourceResult>;
+            provisionAndPersist: (input: IProvisionCloudResourceInput) => Promise<IProvisionCloudResourceResult>;
+        };
+        credentials: {
+            issue: (input: ICloudRuntimeCredentialsInput) => Promise<ICloudRuntimeCredentials>;
+        };
+        getService: () => Promise<CloudService>;
+    };
     /**
      * Cache-related operations for managing product caches.
      */
@@ -3636,9 +3678,178 @@ export default class Ductape implements IDuctape {
         update: (appTag: string, tag: string, data: Partial<IAppVariables>) => Promise<void>;
     };
     /**
-     * Action-related operations for managing app actions.
+     * API operations: run/dispatch app actions, credentials, OAuth, and app action CRUD.
      */
-    actions: {
+    api: {
+        /**
+         * Imports actions for an app from a file.
+         * @param {Object} params - The import parameters.
+         * @param {Buffer} params.file - The file buffer.
+         * @param {ImportDocsTypes} params.type - The import type.
+         * @param {string} params.version - The version.
+         * @param {string} [params.appTag] - The app tag (optional).
+         * @param {boolean} [params.updateIfExists] - Whether to update if actions exist (optional).
+         * @returns {Promise<void>} Resolves when the import is complete. Throws on error.
+         */
+        import: ({ file, type, version, appTag, updateIfExists, isAdminImport, }: {
+            file: Buffer;
+            type: ImportDocsTypes;
+            version: string;
+            appTag?: string;
+            updateIfExists?: boolean;
+            isAdminImport?: boolean;
+        }) => Promise<void>;
+        /**
+         * Updates an action by tag.
+         * @param {string} appTag - The app tag.
+         * @param {string} tag - The action tag.
+         * @param {Partial<IActionUpdate>} data - The action data to update.
+         * @returns {Promise<void>} Resolves when the action is updated. Throws on error.
+         */
+        update: (appTag: string, tag: string, data: Partial<IActionUpdate>) => Promise<void>;
+        /**
+         * Creates an action.
+         * @param {string} appTag - The app tag.
+         * @param {Partial<IActionUpdate> & { tag: string; name: string; resource: string; method: string; folder_id?: string }} data - The action data.
+         * @returns {Promise<void>} Resolves when the action is created. Throws on error.
+         */
+        create: (appTag: string, data: Partial<IActionUpdate> & {
+            tag: string;
+            name: string;
+            resource: string;
+            method: string;
+            folder_id?: string;
+        }) => Promise<void>;
+        /**
+         * Fetches all actions for an app.
+         * @param {string} appTag - The app tag.
+         * @returns {IAppAction[]} The list of actions.
+         */
+        list: (appTag: string) => Promise<IAppAction[]>;
+        /**
+         * Fetches an action by tag.
+         * @param {string} appTag - The app tag.
+         * @param {string} tag - The action tag.
+         * @returns {IAppAction|null} The fetched action, or null if not found.
+         */
+        fetch: (appTag: string, tag: string) => Promise<IAppAction>;
+        /**
+         * Runs an action processor immediately.
+         * @param {IActionProcessorInput} data - The action processor input.
+         * @returns {Promise<any>} The result of the action processing.
+         * @example
+         * await ductape.api.run({
+         *   product: 'my-product',
+         *   env: 'production',
+         *   app: 'stripe',
+         *   action: 'charge',
+         *   input: { amount: 1000, currency: 'usd' }
+         * });
+         */
+        run: (data: IActionProcessorInput) => Promise<any>;
+        /**
+         * Dispatches an action to run as a scheduled job.
+         * @param {IActionDispatchInput} data - The action dispatch input with scheduling options.
+         * @returns {Promise<IDispatchResult>} The dispatch result with job ID and status.
+         * @example
+         * // Run once at a specific time
+         * await ductape.api.dispatch({
+         *   product: 'my-product',
+         *   env: 'production',
+         *   app: 'stripe',
+         *   event: 'charge',
+         *   input: { amount: 1000 },
+         *   schedule: { start_at: Date.now() + 3600000 } // 1 hour from now
+         * });
+         *
+         * // Run on a cron schedule
+         * await ductape.api.dispatch({
+         *   product: 'my-product',
+         *   env: 'production',
+         *   app: 'analytics',
+         *   event: 'daily-report',
+         *   input: {},
+         *   schedule: { cron: '0 9 * * *', tz: 'America/New_York' } // 9 AM daily
+         * });
+         */
+        dispatch: (data: IActionDispatchInput) => Promise<IDispatchResult>;
+        /**
+         * Set shared configuration (credentials) for a product/app/env combination.
+         * Credentials are automatically merged into action inputs before resolution.
+         * @param {IShareCredentialsConfig} config - The credential configuration.
+         * @example
+         * // Define app configuration and set credentials
+         * const stripeConfig = { product: 'my-product', app: 'stripe', env: 'prd' };
+         *
+         * ductape.api.config({
+         *   ...stripeConfig,
+         *   credentials: {
+         *     'headers:Authorization': '$Secret{StripeApiKey}',
+         *   }
+         * });
+         *
+         * // Now all stripe actions automatically include the Authorization header
+         * await ductape.api.run({
+         *   ...stripeConfig,
+         *   action: 'create-charge',
+         *   input: { amount: 1000, currency: 'usd' }
+         * });
+         */
+        config: (config: IShareCredentialsConfig) => void;
+        /**
+         * Set up OAuth configuration with automatic token refresh for a product/app/env combination.
+         * Tokens are stored securely using $Secret{} and automatically refreshed when expired.
+         * @param {IOAuthConfig} config - The OAuth configuration.
+         * @example
+         * // Set up OAuth with automatic refresh using ductape.api.run
+         * await ductape.api.oauth({
+         *   product: 'my-product',
+         *   app: 'salesforce',
+         *   env: 'prd',
+         *   tokens: {
+         *     accessToken: initialAccessToken,
+         *     refreshToken: initialRefreshToken,
+         *   },
+         *   expiresAt: tokenExpiry,
+         *   credentials: (tokens) => ({
+         *     'headers:Authorization': `Bearer ${tokens.accessToken}`
+         *   }),
+         *   onExpiry: async (currentTokens) => {
+         *     // Use ductape.api.run to call your refresh token action
+         *     const response = await ductape.api.run({
+         *       product: 'my-product',
+         *       app: 'salesforce',
+         *       env: 'prd',
+         *       action: 'refresh-token',
+         *       input: {
+         *         'body:grant_type': 'refresh_token',
+         *         'body:refresh_token': currentTokens.refreshToken,
+         *       }
+         *     });
+         *     return {
+         *       tokens: {
+         *         accessToken: response.access_token,
+         *         refreshToken: response.refresh_token || currentTokens.refreshToken
+         *       },
+         *       expiresIn: response.expires_in
+         *     };
+         *   }
+         * });
+         *
+         * // Now all salesforce actions automatically include OAuth tokens
+         * // and refresh automatically when expired
+         * await ductape.api.run({
+         *   product: 'my-product',
+         *   app: 'salesforce',
+         *   env: 'prd',
+         *   action: 'get-contacts',
+         *   input: { limit: 10 }
+         * });
+         */
+        oauth: (config: IOAuthConfig) => Promise<void>;
+    };
+    /** @deprecated Use {@link Ductape.api} instead. */
+    get actions(): {
         /**
          * Imports actions for an app from a file.
          * @param {Object} params - The import parameters.
@@ -3696,7 +3907,7 @@ export default class Ductape implements IDuctape {
          * @param {IActionProcessorInput} data - The action processor input.
          * @returns {Promise<any>} The result of the action processing.
          * @example
-         * await ductape.actions.run({
+         * await ductape.api.run({
          *   product: 'my-product',
          *   env: 'production',
          *   app: 'stripe',
@@ -3711,7 +3922,7 @@ export default class Ductape implements IDuctape {
          * @returns {Promise<IDispatchResult>} The dispatch result with job ID and status.
          * @example
          * // Run once at a specific time
-         * await ductape.actions.dispatch({
+         * await ductape.api.dispatch({
          *   product: 'my-product',
          *   env: 'production',
          *   app: 'stripe',
@@ -3721,7 +3932,7 @@ export default class Ductape implements IDuctape {
          * });
          *
          * // Run on a cron schedule
-         * await ductape.actions.dispatch({
+         * await ductape.api.dispatch({
          *   product: 'my-product',
          *   env: 'production',
          *   app: 'analytics',
@@ -3739,7 +3950,7 @@ export default class Ductape implements IDuctape {
          * // Define app configuration and set credentials
          * const stripeConfig = { product: 'my-product', app: 'stripe', env: 'prd' };
          *
-         * ductape.actions.config({
+         * ductape.api.config({
          *   ...stripeConfig,
          *   credentials: {
          *     'headers:Authorization': '$Secret{StripeApiKey}',
@@ -3747,7 +3958,7 @@ export default class Ductape implements IDuctape {
          * });
          *
          * // Now all stripe actions automatically include the Authorization header
-         * await ductape.actions.run({
+         * await ductape.api.run({
          *   ...stripeConfig,
          *   action: 'create-charge',
          *   input: { amount: 1000, currency: 'usd' }
@@ -3759,8 +3970,8 @@ export default class Ductape implements IDuctape {
          * Tokens are stored securely using $Secret{} and automatically refreshed when expired.
          * @param {IOAuthConfig} config - The OAuth configuration.
          * @example
-         * // Set up OAuth with automatic refresh using ductape.actions.run
-         * await ductape.actions.oauth({
+         * // Set up OAuth with automatic refresh using ductape.api.run
+         * await ductape.api.oauth({
          *   product: 'my-product',
          *   app: 'salesforce',
          *   env: 'prd',
@@ -3773,8 +3984,8 @@ export default class Ductape implements IDuctape {
          *     'headers:Authorization': `Bearer ${tokens.accessToken}`
          *   }),
          *   onExpiry: async (currentTokens) => {
-         *     // Use ductape.actions.run to call your refresh token action
-         *     const response = await ductape.actions.run({
+         *     // Use ductape.api.run to call your refresh token action
+         *     const response = await ductape.api.run({
          *       product: 'my-product',
          *       app: 'salesforce',
          *       env: 'prd',
@@ -3796,7 +4007,7 @@ export default class Ductape implements IDuctape {
          *
          * // Now all salesforce actions automatically include OAuth tokens
          * // and refresh automatically when expired
-         * await ductape.actions.run({
+         * await ductape.api.run({
          *   product: 'my-product',
          *   app: 'salesforce',
          *   env: 'prd',
@@ -3978,6 +4189,7 @@ export default class Ductape implements IDuctape {
      */
     private createNewJobsService;
     private createNewSecretsService;
+    private createNewCloudService;
     /**
      * Create a new SessionsService instance with authenticated config
      * @returns SessionsService instance