@memberjunction/integration-actions 0.0.1 → 5.8.0

package/README.md

@@ -1,45 +1,79 @@
 # @memberjunction/integration-actions
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/integration-actions`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+MJ Actions for triggering MemberJunction integration syncs. Connects the Integration Engine to the MJ Actions + Scheduling system.
+
+## Installation
+
+This package is registered as a workspace package. Add it as a dependency and import it so the `@RegisterClass` decorator fires:
+
+```typescript
+// In your bootstrap or entry point:
+import '@memberjunction/integration-actions';
+```
+
+## Actions
+
+### Run Integration Sync
+
+**Action Name**: `Run Integration Sync`
+
+Triggers a full sync run for a `MJ: Company Integration` record.
+
+| Parameter | Direction | Type | Required | Description |
+|-----------|-----------|------|----------|-------------|
+| `CompanyIntegrationID` | Input | string | Yes | ID of the CompanyIntegration to sync |
+| `TriggerType` | Input | string | No | `Manual`, `Scheduled`, or `Webhook` (default: `Manual`) |
+| `RecordsProcessed` | Output | number | — | Total records processed |
+| `RecordsCreated` | Output | number | — | Records created in MJ |
+| `RecordsUpdated` | Output | number | — | Records updated in MJ |
+| `RecordsDeleted` | Output | number | — | Records deleted in MJ |
+| `RecordsErrored` | Output | number | — | Records that encountered errors |
+| `RecordsSkipped` | Output | number | — | Records that were skipped |
+| `ErrorSummary` | Output | string | — | JSON array of first 10 errors (only when errors exist) |
+
+**Result Codes**:
+- `SUCCESS` — Sync completed without errors
+- `SYNC_COMPLETED_WITH_ERRORS` — Sync completed but some records failed
+- `MISSING_PARAMETER` — Required `CompanyIntegrationID` not provided
+- `UNEXPECTED_ERROR` — Unhandled exception during sync
+
+## Scheduling via MJ Scheduler
+
+1. Create an `MJ: Actions` record for `Run Integration Sync`
+2. Create an `MJ: Action Params` record for `CompanyIntegrationID`
+3. Set up a Scheduled Job pointing to this action
+4. The scheduler calls the action on the configured cadence
+
+## Usage from Code
+
+```typescript
+import '@memberjunction/integration-actions'; // ensure registration
+import { ActionEngine } from '@memberjunction/actions';
+
+const engine = ActionEngine.Instance;
+const result = await engine.RunAction({
+    ActionName: 'Run Integration Sync',
+    ContextUser: currentUser,
+    Params: [
+        { Name: 'CompanyIntegrationID', Type: 'Input', Value: 'your-ci-id' },
+        { Name: 'TriggerType', Type: 'Input', Value: 'Scheduled' },
+    ],
+});
+```
+
+## Direct Orchestrator Usage
+
+For server-side code that doesn't go through the Actions system:
+
+```typescript
+import { IntegrationOrchestrator } from '@memberjunction/integration-engine';
+
+const orchestrator = new IntegrationOrchestrator();
+const result = await orchestrator.RunSync(
+    companyIntegrationID,
+    contextUser,
+    'Manual',
+    (progress) => console.log(`${progress.PercentComplete}%`),
+    (notification) => console.log(notification.Subject)
+);
+```

package/dist/RunSyncAction.d.ts

@@ -0,0 +1,29 @@
+import { BaseAction } from '@memberjunction/actions';
+import { ActionResultSimple, RunActionParams } from '@memberjunction/actions-base';
+/**
+ * MJ Action that triggers a sync for a CompanyIntegration.
+ *
+ * Parameters (Input):
+ *   - CompanyIntegrationID (required): ID of the CompanyIntegration to sync
+ *   - TriggerType (optional): 'Scheduled' | 'Manual' | 'Webhook'  (default: 'Manual')
+ *   - FullSync (optional): 'true' to force a full sync ignoring watermarks
+ *   - EntityMapIDs (optional): comma-separated list of EntityMapIDs to restrict the sync
+ *
+ * Parameters (Output):
+ *   - RecordsProcessed: total records processed
+ *   - RecordsCreated: records created
+ *   - RecordsUpdated: records updated
+ *   - RecordsDeleted: records deleted
+ *   - RecordsErrored: records that encountered errors
+ *   - RecordsSkipped: records that were skipped
+ *   - ErrorSummary: JSON string of error details (first 10 errors)
+ */
+export declare class RunSyncAction extends BaseAction {
+    protected InternalRunAction(params: RunActionParams): Promise<ActionResultSimple>;
+    private parseTriggerType;
+    private buildResultMessage;
+    private addOutputParams;
+    private getStringParam;
+    private addOutputParam;
+}
+//# sourceMappingURL=RunSyncAction.d.ts.map

package/dist/RunSyncAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunSyncAction.d.ts","sourceRoot":"","sources":["../src/RunSyncAction.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAe,MAAM,8BAA8B,CAAC;AAGhG;;;;;;;;;;;;;;;;;GAiBG;AACH,qBACa,aAAc,SAAQ,UAAU;cAEzB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAuCvF,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,kBAAkB;IAY1B,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,cAAc;CAOzB"}

package/dist/RunSyncAction.js

@@ -0,0 +1,117 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { RegisterClass } from '@memberjunction/global';
+import { LogError } from '@memberjunction/core';
+import { BaseAction } from '@memberjunction/actions';
+import { ActionParam } from '@memberjunction/actions-base';
+import { IntegrationOrchestrator } from '@memberjunction/integration-engine';
+/**
+ * MJ Action that triggers a sync for a CompanyIntegration.
+ *
+ * Parameters (Input):
+ *   - CompanyIntegrationID (required): ID of the CompanyIntegration to sync
+ *   - TriggerType (optional): 'Scheduled' | 'Manual' | 'Webhook'  (default: 'Manual')
+ *   - FullSync (optional): 'true' to force a full sync ignoring watermarks
+ *   - EntityMapIDs (optional): comma-separated list of EntityMapIDs to restrict the sync
+ *
+ * Parameters (Output):
+ *   - RecordsProcessed: total records processed
+ *   - RecordsCreated: records created
+ *   - RecordsUpdated: records updated
+ *   - RecordsDeleted: records deleted
+ *   - RecordsErrored: records that encountered errors
+ *   - RecordsSkipped: records that were skipped
+ *   - ErrorSummary: JSON string of error details (first 10 errors)
+ */
+let RunSyncAction = class RunSyncAction extends BaseAction {
+    async InternalRunAction(params) {
+        try {
+            const companyIntegrationID = this.getStringParam(params, 'CompanyIntegrationID');
+            if (!companyIntegrationID) {
+                return {
+                    Success: false,
+                    ResultCode: 'MISSING_PARAMETER',
+                    Message: "Parameter 'CompanyIntegrationID' is required"
+                };
+            }
+            const triggerType = this.parseTriggerType(this.getStringParam(params, 'TriggerType'));
+            const orchestrator = new IntegrationOrchestrator();
+            const result = await orchestrator.RunSync(companyIntegrationID, params.ContextUser, triggerType);
+            this.addOutputParams(params, result);
+            return {
+                Success: result.Success,
+                ResultCode: result.Success ? 'SUCCESS' : 'SYNC_COMPLETED_WITH_ERRORS',
+                Message: this.buildResultMessage(result),
+                Params: params.Params
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            LogError(`[RunSyncAction] Unexpected error: ${message}`);
+            return {
+                Success: false,
+                ResultCode: 'UNEXPECTED_ERROR',
+                Message: message
+            };
+        }
+    }
+    parseTriggerType(value) {
+        if (value === 'Scheduled' || value === 'Webhook')
+            return value;
+        return 'Manual';
+    }
+    buildResultMessage(result) {
+        const parts = [
+            `Processed: ${result.RecordsProcessed}`,
+            `Created: ${result.RecordsCreated}`,
+            `Updated: ${result.RecordsUpdated}`,
+        ];
+        if (result.RecordsDeleted > 0)
+            parts.push(`Deleted: ${result.RecordsDeleted}`);
+        if (result.RecordsErrored > 0)
+            parts.push(`Errors: ${result.RecordsErrored}`);
+        if (result.RecordsSkipped > 0)
+            parts.push(`Skipped: ${result.RecordsSkipped}`);
+        return parts.join(', ');
+    }
+    addOutputParams(params, result) {
+        const outputs = [
+            { name: 'RecordsProcessed', value: result.RecordsProcessed },
+            { name: 'RecordsCreated', value: result.RecordsCreated },
+            { name: 'RecordsUpdated', value: result.RecordsUpdated },
+            { name: 'RecordsDeleted', value: result.RecordsDeleted },
+            { name: 'RecordsErrored', value: result.RecordsErrored },
+            { name: 'RecordsSkipped', value: result.RecordsSkipped },
+        ];
+        for (const { name, value } of outputs) {
+            this.addOutputParam(params, name, value);
+        }
+        if (result.Errors.length > 0) {
+            this.addOutputParam(params, 'ErrorSummary', JSON.stringify(result.Errors.slice(0, 10)));
+        }
+    }
+    getStringParam(params, name) {
+        const nameLower = name.toLowerCase();
+        const param = params.Params?.find(p => p.Name.trim().toLowerCase() === nameLower);
+        if (!param || param.Value == null)
+            return undefined;
+        const value = String(param.Value).trim();
+        return value.length > 0 ? value : undefined;
+    }
+    addOutputParam(params, name, value) {
+        const outputParam = new ActionParam();
+        outputParam.Name = name;
+        outputParam.Type = 'Output';
+        outputParam.Value = value;
+        params.Params.push(outputParam);
+    }
+};
+RunSyncAction = __decorate([
+    RegisterClass(BaseAction, 'Run Integration Sync')
+], RunSyncAction);
+export { RunSyncAction };
+//# sourceMappingURL=RunSyncAction.js.map

package/dist/RunSyncAction.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './RunSyncAction.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './RunSyncAction.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/package.json

@@ -1,10 +1,34 @@
 {
   "name": "@memberjunction/integration-actions",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/integration-actions",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "type": "module",
+  "version": "5.8.0",
+  "description": "MemberJunction Integration Engine Actions - MJ Actions for triggering and managing integration syncs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@memberjunction/actions": "5.8.0",
+    "@memberjunction/actions-base": "5.8.0",
+    "@memberjunction/core": "5.8.0",
+    "@memberjunction/global": "5.8.0",
+    "@memberjunction/integration-engine": "5.8.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "tsc-alias": "^1.8.16",
+    "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  },
+  "author": "MemberJunction.com",
+  "license": "ISC"
 }