@memberjunction/esignature 0.0.1 → 5.40.0

package/dist/BaseSignatureProvider.d.ts

@@ -0,0 +1,77 @@
+import { CreateEnvelopeRequest, EmbeddedSigningRequest, EnvelopeResult, EnvelopeStatusResult, NormalizedSignatureEvent, OperationResult, SignatureOperation, SignatureProviderConfig, SignedDocumentResult, SigningUrlResult, TemplateEnvelopeRequest, WebhookVerificationResult } from './types.js';
+/**
+ * Abstract base for all eSignature providers. Concrete drivers (DocuSign, Adobe Sign, …) live in
+ * their own packages and register via `@RegisterClass(BaseSignatureProvider, '<DriverKey>')`, where
+ * `<DriverKey>` matches `MJ: Signature Providers.ServerDriverKey`. The engine resolves a driver with
+ * `MJGlobal.Instance.ClassFactory.CreateInstance(BaseSignatureProvider, driverKey)` — never `new`.
+ *
+ * Design contract:
+ * - **Core operations are `abstract`** — every driver must implement them.
+ * - **Optional operations are non-abstract** with a "not supported" default, advertised via
+ *   {@link getSupportedOperations}. This mirrors the Communication provider idiom.
+ * - The provider is **stateless w.r.t. credentials**: the engine resolves and decrypts credentials,
+ *   then hands them to {@link initialize}. Token refreshes are persisted via the engine-supplied
+ *   `onTokenRefresh` callback on {@link SignatureProviderConfig}.
+ */
+export declare abstract class BaseSignatureProvider {
+    /**
+     * Driver key for this provider. MUST equal the `@RegisterClass` key and
+     * `MJ: Signature Providers.ServerDriverKey`.
+     */
+    protected abstract readonly providerKey: string;
+    /** One-time per-instance initialization with the merged + decrypted config from the engine. */
+    abstract initialize(config: SignatureProviderConfig): Promise<void>;
+    /** True once {@link initialize} has supplied all credentials this provider requires. */
+    abstract get IsConfigured(): boolean;
+    /** Create (and, per `sendImmediately`, send) a signature envelope. */
+    abstract CreateEnvelope(req: CreateEnvelopeRequest): Promise<EnvelopeResult>;
+    /** Fetch the current status of a previously created envelope. */
+    abstract GetEnvelopeStatus(externalEnvelopeId: string): Promise<EnvelopeStatusResult>;
+    /** Download the executed/signed document for a completed envelope. */
+    abstract DownloadSignedDocument(externalEnvelopeId: string): Promise<SignedDocumentResult>;
+    /** Void/cancel an in-flight envelope with a reason. */
+    abstract VoidEnvelope(externalEnvelopeId: string, reason: string): Promise<OperationResult>;
+    /** Create an embedded (in-app) signing URL. Not all providers support this. */
+    CreateEmbeddedSigningUrl(_req: EmbeddedSigningRequest): Promise<SigningUrlResult>;
+    /** Create an envelope from a provider-hosted template. Not all providers support this. */
+    ApplyTemplate(_req: TemplateEnvelopeRequest): Promise<EnvelopeResult>;
+    /** Re-send the signing notification to outstanding recipients. Not all providers support this. */
+    ResendNotification(_externalEnvelopeId: string): Promise<OperationResult>;
+    /** The operations this driver actually supports. */
+    abstract getSupportedOperations(): SignatureOperation[];
+    /** Convenience predicate over {@link getSupportedOperations}. */
+    supportsOperation(op: SignatureOperation): boolean;
+    /**
+     * Normalize a provider webhook payload onto our vocabulary. This is the *parse* step only — it
+     * needs no secret, so the engine can call it on a bare driver to discover which envelope an
+     * event refers to. Returns `null` for payloads this driver doesn't handle. Default: not handled.
+     *
+     * Authenticity is checked separately by {@link VerifyWebhookSignature}, which runs on a
+     * credential-initialized driver.
+     */
+    ParseWebhookEvent(_payload: unknown, _headers: Record<string, string>): NormalizedSignatureEvent | null;
+    /**
+     * Verify the authenticity of an inbound webhook (HMAC / signature). The eSignature webhook
+     * endpoint is unauthenticated and mutates signature-request status, so the engine consults this
+     * before applying any event under a **verify-if-configured** policy:
+     *   - `Verified`      → a secret is configured and the signature matched → engine accepts.
+     *   - `Failed`        → a secret is configured but the signature was missing/invalid → **reject.**
+     *   - `NotConfigured` → no secret configured → engine accepts (logged), so the endpoint works
+     *                       during setup and tightens to strict automatically once a key is set.
+     *
+     * Default is `NotConfigured`: a driver that doesn't implement verification has no secret to
+     * check. Implementations read their shared secret from `this.config` (e.g.
+     * {@link SignatureProviderConfig.connectHmacKey}) — sourced from the account's encrypted
+     * credential, never an environment variable.
+     *
+     * Providers verify in whichever way their API prescribes:
+     *   - over the EXACT raw bytes (DocuSign Connect HMAC) — use `rawBody`;
+     *   - over fields inside the parsed payload (Dropbox Sign `event_hash`) — use `payload`.
+     *
+     * @param _rawBody The exact bytes received, for byte-accurate HMAC. Undefined if unavailable.
+     * @param _headers Inbound headers (may carry the provider signature header).
+     * @param _payload The parsed payload, for providers that sign payload fields rather than bytes.
+     */
+    VerifyWebhookSignature(_rawBody: Buffer | undefined, _headers: Record<string, string>, _payload?: unknown): WebhookVerificationResult;
+}
+//# sourceMappingURL=BaseSignatureProvider.d.ts.map

package/dist/BaseSignatureProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseSignatureProvider.d.ts","sourceRoot":"","sources":["../src/BaseSignatureProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACxB,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,yBAAyB,EAC5B,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;GAaG;AACH,8BAAsB,qBAAqB;IACvC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAEhD,+FAA+F;aAC/E,UAAU,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1E,wFAAwF;IACxF,aAAoB,YAAY,IAAI,OAAO,CAAC;IAI5C,sEAAsE;aACtD,cAAc,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;IAEnF,iEAAiE;aACjD,iBAAiB,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAE5F,sEAAsE;aACtD,sBAAsB,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAEjG,uDAAuD;aACvC,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIlG,+EAA+E;IAClE,wBAAwB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAI9F,0FAA0F;IAC7E,aAAa,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,cAAc,CAAC;IAIlF,kGAAkG;IACrF,kBAAkB,CAAC,mBAAmB,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAMtF,oDAAoD;aACpC,sBAAsB,IAAI,kBAAkB,EAAE;IAE9D,iEAAiE;IAC1D,iBAAiB,CAAC,EAAE,EAAE,kBAAkB,GAAG,OAAO;IAMzD;;;;;;;OAOG;IACI,iBAAiB,CACpB,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,wBAAwB,GAAG,IAAI;IAIlC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,sBAAsB,CACzB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,QAAQ,CAAC,EAAE,OAAO,GACnB,yBAAyB;CAG/B"}

package/dist/BaseSignatureProvider.js

@@ -0,0 +1,71 @@
+/**
+ * Abstract base for all eSignature providers. Concrete drivers (DocuSign, Adobe Sign, …) live in
+ * their own packages and register via `@RegisterClass(BaseSignatureProvider, '<DriverKey>')`, where
+ * `<DriverKey>` matches `MJ: Signature Providers.ServerDriverKey`. The engine resolves a driver with
+ * `MJGlobal.Instance.ClassFactory.CreateInstance(BaseSignatureProvider, driverKey)` — never `new`.
+ *
+ * Design contract:
+ * - **Core operations are `abstract`** — every driver must implement them.
+ * - **Optional operations are non-abstract** with a "not supported" default, advertised via
+ *   {@link getSupportedOperations}. This mirrors the Communication provider idiom.
+ * - The provider is **stateless w.r.t. credentials**: the engine resolves and decrypts credentials,
+ *   then hands them to {@link initialize}. Token refreshes are persisted via the engine-supplied
+ *   `onTokenRefresh` callback on {@link SignatureProviderConfig}.
+ */
+export class BaseSignatureProvider {
+    // ---- Optional operations (default: "not supported") ------------------------------------------
+    /** Create an embedded (in-app) signing URL. Not all providers support this. */
+    async CreateEmbeddedSigningUrl(_req) {
+        return { Success: false, ErrorMessage: `${this.providerKey} does not support embedded signing.` };
+    }
+    /** Create an envelope from a provider-hosted template. Not all providers support this. */
+    async ApplyTemplate(_req) {
+        return { Success: false, ErrorMessage: `${this.providerKey} does not support templates.` };
+    }
+    /** Re-send the signing notification to outstanding recipients. Not all providers support this. */
+    async ResendNotification(_externalEnvelopeId) {
+        return { Success: false, ErrorMessage: `${this.providerKey} does not support resend.` };
+    }
+    /** Convenience predicate over {@link getSupportedOperations}. */
+    supportsOperation(op) {
+        return this.getSupportedOperations().includes(op);
+    }
+    // ---- Inbound webhook (Connect / event callbacks) --------------------------------------------
+    /**
+     * Normalize a provider webhook payload onto our vocabulary. This is the *parse* step only — it
+     * needs no secret, so the engine can call it on a bare driver to discover which envelope an
+     * event refers to. Returns `null` for payloads this driver doesn't handle. Default: not handled.
+     *
+     * Authenticity is checked separately by {@link VerifyWebhookSignature}, which runs on a
+     * credential-initialized driver.
+     */
+    ParseWebhookEvent(_payload, _headers) {
+        return null;
+    }
+    /**
+     * Verify the authenticity of an inbound webhook (HMAC / signature). The eSignature webhook
+     * endpoint is unauthenticated and mutates signature-request status, so the engine consults this
+     * before applying any event under a **verify-if-configured** policy:
+     *   - `Verified`      → a secret is configured and the signature matched → engine accepts.
+     *   - `Failed`        → a secret is configured but the signature was missing/invalid → **reject.**
+     *   - `NotConfigured` → no secret configured → engine accepts (logged), so the endpoint works
+     *                       during setup and tightens to strict automatically once a key is set.
+     *
+     * Default is `NotConfigured`: a driver that doesn't implement verification has no secret to
+     * check. Implementations read their shared secret from `this.config` (e.g.
+     * {@link SignatureProviderConfig.connectHmacKey}) — sourced from the account's encrypted
+     * credential, never an environment variable.
+     *
+     * Providers verify in whichever way their API prescribes:
+     *   - over the EXACT raw bytes (DocuSign Connect HMAC) — use `rawBody`;
+     *   - over fields inside the parsed payload (Dropbox Sign `event_hash`) — use `payload`.
+     *
+     * @param _rawBody The exact bytes received, for byte-accurate HMAC. Undefined if unavailable.
+     * @param _headers Inbound headers (may carry the provider signature header).
+     * @param _payload The parsed payload, for providers that sign payload fields rather than bytes.
+     */
+    VerifyWebhookSignature(_rawBody, _headers, _payload) {
+        return 'NotConfigured';
+    }
+}
+//# sourceMappingURL=BaseSignatureProvider.js.map

package/dist/BaseSignatureProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseSignatureProvider.js","sourceRoot":"","sources":["../src/BaseSignatureProvider.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAgB,qBAAqB;IA2BvC,iGAAiG;IAEjG,+EAA+E;IACxE,KAAK,CAAC,wBAAwB,CAAC,IAA4B;QAC9D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,WAAW,qCAAqC,EAAE,CAAC;IACtG,CAAC;IAED,0FAA0F;IACnF,KAAK,CAAC,aAAa,CAAC,IAA6B;QACpD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,WAAW,8BAA8B,EAAE,CAAC;IAC/F,CAAC;IAED,kGAAkG;IAC3F,KAAK,CAAC,kBAAkB,CAAC,mBAA2B;QACvD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,WAAW,2BAA2B,EAAE,CAAC;IAC5F,CAAC;IAOD,iEAAiE;IAC1D,iBAAiB,CAAC,EAAsB;QAC3C,OAAO,IAAI,CAAC,sBAAsB,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,gGAAgG;IAEhG;;;;;;;OAOG;IACI,iBAAiB,CACpB,QAAiB,EACjB,QAAgC;QAEhC,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,sBAAsB,CACzB,QAA4B,EAC5B,QAAgC,EAChC,QAAkB;QAElB,OAAO,eAAe,CAAC;IAC3B,CAAC;CACJ"}

package/dist/SignatureEngineBase.d.ts

@@ -0,0 +1,33 @@
+import { BaseEngine, IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { MJSignatureAccountEntity, MJSignatureProviderEntity } from '@memberjunction/core-entities';
+/** A signature account paired with its resolved provider entity. */
+export interface SignatureAccountWithProvider {
+    account: MJSignatureAccountEntity;
+    provider: MJSignatureProviderEntity;
+}
+/**
+ * Metadata cache for the eSignature subsystem — providers + accounts. Extends {@link BaseEngine}
+ * so saves/deletes/remote-invalidations on those entities keep the cache fresh automatically.
+ *
+ * This is the metadata-only layer (safe for any context that has the entities). The server-side
+ * {@link SignatureEngine} wraps this and adds driver resolution, credential decryption, and the
+ * envelope lifecycle operations. Mirrors the FileStorageEngineBase / FileStorageEngine split.
+ */
+export declare class SignatureEngineBase extends BaseEngine<SignatureEngineBase> {
+    static get Instance(): SignatureEngineBase;
+    private _accounts;
+    private _providers;
+    /** Load signature accounts + providers into the cache (idempotent unless forceRefresh). */
+    Config(forceRefresh?: boolean, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<void>;
+    get Accounts(): MJSignatureAccountEntity[];
+    get Providers(): MJSignatureProviderEntity[];
+    /** Accounts joined to their provider entity; accounts whose provider is missing are dropped. */
+    get AccountsWithProviders(): SignatureAccountWithProvider[];
+    GetAccountById(accountId: string): MJSignatureAccountEntity | undefined;
+    GetProviderById(providerId: string): MJSignatureProviderEntity | undefined;
+    GetAccountByName(name: string): MJSignatureAccountEntity | undefined;
+    GetProviderByDriverKey(driverKey: string): MJSignatureProviderEntity | undefined;
+    /** Resolve an account with its provider; null if either is missing. */
+    GetAccountWithProvider(accountId: string): SignatureAccountWithProvider | null;
+}
+//# sourceMappingURL=SignatureEngineBase.d.ts.map

package/dist/SignatureEngineBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SignatureEngineBase.d.ts","sourceRoot":"","sources":["../src/SignatureEngineBase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA4B,iBAAiB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEzG,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAEpG,oEAAoE;AACpE,MAAM,WAAW,4BAA4B;IACzC,OAAO,EAAE,wBAAwB,CAAC;IAClC,QAAQ,EAAE,yBAAyB,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,UAAU,CAAC,mBAAmB,CAAC;IACpE,WAAkB,QAAQ,IAAI,mBAAmB,CAEhD;IAED,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,UAAU,CAAmC;IAErD,2FAA2F;IAC9E,MAAM,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBhH,IAAW,QAAQ,IAAI,wBAAwB,EAAE,CAEhD;IAED,IAAW,SAAS,IAAI,yBAAyB,EAAE,CAElD;IAED,gGAAgG;IAChG,IAAW,qBAAqB,IAAI,4BAA4B,EAAE,CAQjE;IAIM,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,wBAAwB,GAAG,SAAS;IAIvE,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS;IAI1E,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,wBAAwB,GAAG,SAAS;IAIpE,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS;IAKvF,uEAAuE;IAChE,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,4BAA4B,GAAG,IAAI;CAQxF"}

package/dist/SignatureEngineBase.js

@@ -0,0 +1,78 @@
+import { BaseEngine } from '@memberjunction/core';
+import { UUIDsEqual } from '@memberjunction/global';
+/**
+ * Metadata cache for the eSignature subsystem — providers + accounts. Extends {@link BaseEngine}
+ * so saves/deletes/remote-invalidations on those entities keep the cache fresh automatically.
+ *
+ * This is the metadata-only layer (safe for any context that has the entities). The server-side
+ * {@link SignatureEngine} wraps this and adds driver resolution, credential decryption, and the
+ * envelope lifecycle operations. Mirrors the FileStorageEngineBase / FileStorageEngine split.
+ */
+export class SignatureEngineBase extends BaseEngine {
+    constructor() {
+        super(...arguments);
+        this._accounts = [];
+        this._providers = [];
+    }
+    static get Instance() {
+        return super.getInstance();
+    }
+    /** Load signature accounts + providers into the cache (idempotent unless forceRefresh). */
+    async Config(forceRefresh, contextUser, provider) {
+        const configs = [
+            {
+                Type: 'entity',
+                EntityName: 'MJ: Signature Accounts',
+                PropertyName: '_accounts',
+                CacheLocal: true,
+            },
+            {
+                Type: 'entity',
+                EntityName: 'MJ: Signature Providers',
+                PropertyName: '_providers',
+                CacheLocal: true,
+            },
+        ];
+        await this.Load(configs, provider, forceRefresh, contextUser);
+    }
+    // ---- Cached-data getters ----------------------------------------------------------------------
+    get Accounts() {
+        return this._accounts || [];
+    }
+    get Providers() {
+        return this._providers || [];
+    }
+    /** Accounts joined to their provider entity; accounts whose provider is missing are dropped. */
+    get AccountsWithProviders() {
+        const providerMap = new Map();
+        this.Providers.forEach((p) => providerMap.set(p.ID, p));
+        return this.Accounts.map((account) => {
+            const provider = providerMap.get(account.SignatureProviderID);
+            return provider ? { account, provider } : null;
+        }).filter((item) => item !== null);
+    }
+    // ---- Lookups ----------------------------------------------------------------------------------
+    GetAccountById(accountId) {
+        return this.Accounts.find((a) => UUIDsEqual(a.ID, accountId));
+    }
+    GetProviderById(providerId) {
+        return this.Providers.find((p) => UUIDsEqual(p.ID, providerId));
+    }
+    GetAccountByName(name) {
+        return this.Accounts.find((a) => a.Name?.trim().toLowerCase() === name.trim().toLowerCase());
+    }
+    GetProviderByDriverKey(driverKey) {
+        const key = driverKey.trim().toLowerCase();
+        return this.Providers.find((p) => p.ServerDriverKey?.trim().toLowerCase() === key);
+    }
+    /** Resolve an account with its provider; null if either is missing. */
+    GetAccountWithProvider(accountId) {
+        const account = this.GetAccountById(accountId);
+        if (!account) {
+            return null;
+        }
+        const provider = this.GetProviderById(account.SignatureProviderID);
+        return provider ? { account, provider } : null;
+    }
+}
+//# sourceMappingURL=SignatureEngineBase.js.map

package/dist/SignatureEngineBase.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './BaseSignatureProvider.js';
+export * from './SignatureEngineBase.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":"AASA,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+// PUBLIC API SURFACE AREA.
+// Provider contract (types + BaseSignatureProvider) plus the metadata-cache engine
+// (SignatureEngineBase). These depend only on @memberjunction/core + core-entities, both of which
+// are client-safe, so this entry stays importable from the browser. SignatureEngineBase mirrors
+// FileStorageEngineBase: a BaseEngine that caches the Providers + Accounts metadata.
+//
+// The credential-decrypting, DB-writing server engine (SignatureEngine) and its driver-init helper
+// are intentionally NOT exported here — import them from '@memberjunction/esignature/server' so
+// client bundles stay free of the server-only @memberjunction/credentials dependency.
+export * from './types.js';
+export * from './BaseSignatureProvider.js';
+export * from './SignatureEngineBase.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,2BAA2B;AAC3B,mFAAmF;AACnF,kGAAkG;AAClG,gGAAgG;AAChG,qFAAqF;AACrF,EAAE;AACF,mGAAmG;AACnG,gGAAgG;AAChG,sFAAsF;AACtF,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC"}

package/dist/server/SignatureEngine.d.ts

@@ -0,0 +1,137 @@
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { BaseSingleton } from '@memberjunction/global';
+import { BaseSignatureProvider } from '../BaseSignatureProvider.js';
+import { EnvelopeStatus, NormalizedSignatureEvent, OperationResult, SignatureDocumentInput, SignatureRecipientInput } from '../types.js';
+import { SignatureEngineBase } from '../SignatureEngineBase.js';
+/** Input for {@link SignatureEngine.SendForSignature}. */
+export interface SendForSignatureOptions {
+    /** Account (provider instance) to send through. */
+    signatureAccountId: string;
+    /** Envelope title / email subject. */
+    title: string;
+    message?: string;
+    /** Documents to sign. The caller resolves bytes (e.g. from an Artifact Version). */
+    documents: SignatureDocumentInput[];
+    /** Signers. */
+    recipients: SignatureRecipientInput[];
+    /** Optional Artifact reference recorded against the (first) document for provenance. */
+    artifactId?: string;
+    artifactVersionId?: string;
+    /** Polymorphic originating record (entity half). */
+    entityId?: string;
+    /** Polymorphic originating record (record half). */
+    recordId?: string;
+    /** true → send immediately; false → create as draft. Defaults to true. */
+    sendImmediately?: boolean;
+    /** Provider custom fields. */
+    metadata?: Record<string, string>;
+    contextUser: UserInfo;
+    provider?: IMetadataProvider;
+}
+/** Result of {@link SignatureEngine.SendForSignature}. */
+export interface SendForSignatureResult {
+    Success: boolean;
+    signatureRequestId?: string;
+    externalEnvelopeId?: string;
+    status?: EnvelopeStatus;
+    ErrorMessage?: string;
+}
+/** Result of {@link SignatureEngine.RefreshStatus}. */
+export interface RefreshStatusResult {
+    Success: boolean;
+    status?: EnvelopeStatus;
+    ErrorMessage?: string;
+}
+/** Result of {@link SignatureEngine.DownloadSigned}. */
+export interface DownloadSignedResult {
+    Success: boolean;
+    document?: {
+        bytes: Buffer;
+        filename: string;
+        contentType: string;
+    };
+    ErrorMessage?: string;
+}
+/**
+ * Server-side eSignature engine. Resolves providers via the ClassFactory, decrypts credentials via
+ * the Credential Engine, persists the envelope lifecycle across the six `MJ: Signature*` entities,
+ * and normalizes inbound webhooks. Wraps {@link SignatureEngineBase} (the metadata cache) using the
+ * same containment pattern as FileStorageEngine.
+ *
+ * Multi-provider rule (CLAUDE.md): every method accepts `contextUser` and an optional
+ * `IMetadataProvider`; the global `Metadata.Provider` is used only as an explicit fallback.
+ */
+export declare class SignatureEngine extends BaseSingleton<SignatureEngine> {
+    private _loaded;
+    private _loading;
+    private _loadingPromise;
+    private _contextUser;
+    /** Initialized drivers keyed by account ID. */
+    private _driverCache;
+    static get Instance(): SignatureEngine;
+    protected get Base(): SignatureEngineBase;
+    get Loaded(): boolean;
+    get Accounts(): import("@memberjunction/core-entities").MJSignatureAccountEntity[];
+    get Providers(): import("@memberjunction/core-entities").MJSignatureProviderEntity[];
+    /** Load metadata + pre-initialize active drivers. Idempotent unless forceRefresh. */
+    Config(forceRefresh?: boolean, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<void>;
+    private innerLoad;
+    /** (Re)initialize drivers for all active accounts. Failures are logged, not thrown. */
+    RefreshDriverCache(): Promise<void>;
+    /** Resolve (and cache) an initialized driver for an account. */
+    GetDriver(accountId: string, contextUser: UserInfo): Promise<BaseSignatureProvider>;
+    /**
+     * Create the lifecycle records, send the envelope through the provider, and persist the outcome.
+     */
+    SendForSignature(options: SendForSignatureOptions): Promise<SendForSignatureResult>;
+    /** Poll the provider for current status and persist it (plus recipient statuses). */
+    RefreshStatus(requestId: string, contextUser: UserInfo, provider?: IMetadataProvider): Promise<RefreshStatusResult>;
+    /** Download the executed document for a completed envelope. */
+    DownloadSigned(requestId: string, contextUser: UserInfo, provider?: IMetadataProvider): Promise<DownloadSignedResult>;
+    /** Void/cancel an in-flight envelope. */
+    Void(requestId: string, reason: string, contextUser: UserInfo, provider?: IMetadataProvider): Promise<OperationResult>;
+    /**
+     * Normalize an inbound provider webhook and apply the status — fail-closed on authenticity.
+     *
+     * Flow (no env vars; HMAC secret lives in the account credential):
+     *  1. Parse the payload on a bare driver (parsing needs no secret) to discover the envelope.
+     *  2. Find the owning MJ: Signature Request, hence its account.
+     *  3. Resolve the account's *credential-initialized* driver and require
+     *     {@link BaseSignatureProvider.VerifyWebhookSignature} to pass over the raw bytes.
+     *  4. Only then apply the status.
+     *
+     * @param rawBody The exact request bytes, required for byte-accurate HMAC verification.
+     */
+    RecordWebhookEvent(driverKey: string, payload: unknown, headers: Record<string, string>, contextUser: UserInfo, rawBody?: Buffer, provider?: IMetadataProvider): Promise<{
+        Success: boolean;
+        event?: NormalizedSignatureEvent;
+        ErrorMessage?: string;
+    }>;
+    /**
+     * Resolve the documents to send. Caller-supplied `documents` win; if none are given and an
+     * `artifactVersionId` is provided, load that version's bytes from the Artifacts subsystem.
+     * (`artifactId` without a version is recorded as provenance only — we don't guess a version.)
+     */
+    private resolveDocuments;
+    private createRequestRecord;
+    private persistDocuments;
+    private persistRecipients;
+    private persistSentRequest;
+    /**
+     * Record the executed document: write the bytes back into the Artifacts subsystem (new Artifact
+     * + Version) and add a `Role='Signed'` document row linked to that version. If no File Storage
+     * Account is configured, fall back to recording the row without an artifact link (the caller
+     * still receives the bytes) — a successful download is never lost over missing storage setup.
+     */
+    private recordSignedDocument;
+    /** Apply a normalized status to a request, stamping CompletedAt on terminal completion. */
+    private applyStatus;
+    private logOperation;
+    private loadRequest;
+    private findRequestByEnvelopeId;
+    private resolveDriverByKey;
+    /** Coerce a normalized status (which may be 'Unknown') into a DB-persistable status. */
+    private persistableStatus;
+    private saveOrThrow;
+}
+//# sourceMappingURL=SignatureEngine.d.ts.map

package/dist/server/SignatureEngine.d.ts.map

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