@superdurable/connector-docusign 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # DocuSign TypeScript connector
 
-`@superdurable/connector-docusign` provides five eSignature operations for Dex Flows: `createEnvelopeFromTemplate`, `getEnvelope`, `listEnvelopeRecipients`, `voidEnvelope`, and `downloadCombinedDocument`. The package uses the manifest's production and developer OAuth methods, with automatic refresh through the generated credential wiring. DocuSign Connect trigger delivery remains Go-only.
+Install `@superdurable/connector-docusign@0.2.0` with `@superdurable/connectors-sdk@0.11.0` and `@superdurable/dex` 1.28 or newer. It provides five eSignature operations for Dex Flows: `createEnvelopeFromTemplate`, `getEnvelope`, `listEnvelopeRecipients`, `voidEnvelope`, and `downloadCombinedDocument`, and from 0.2.0 the `envelopeEventReceived` Connect Trigger. The package uses the manifest's production and developer OAuth methods, with automatic refresh through the generated credential wiring.
 
 The package exports generated operation-specific Step factories, typed models, mock cases, `DocuSignClient`, and `newProjectConnection`. Applications configure a named DocuSign connection in Dex Web using the [connector authorization guide](../README.md). Never put access tokens, refresh tokens, client secrets, Connect HMAC keys, or signed PDFs in Flow inputs, Attributes, Results, or logs.
 
@@ -9,3 +9,15 @@ The [envelope status example](examples/envelope-status/README.md) is a runnable
 The optional `CombinedDocumentStore` supplied to `DocuSignClient` stores a downloaded PDF outside Dex and returns a safe location of at most 1024 bytes. Without a store, `downloadCombinedDocument` returns only its byte count and SHA-256 digest. A store must consume the whole content atomically and be safe to call again after a retry.
 
 From this package directory, run `npm ci`, `npm run check`, and `npm run test:integration` with `DEX_FLOW_SERVICE_ADDRESS` pointing to a running `dexcli dev` server.
+
+## Triggers
+
+From 0.2.0, `envelopeEventReceived` receives HMAC-verified DocuSign Connect `envelope-completed`, `envelope-declined`, and `envelope-voided` events in the JSON SIM format, at parity with the Go connector. The runnable [envelope outcome example](examples/envelope-outcome/README.md) sends an envelope tagged with a hidden `dexSigningRequestId` custom field and completes when Connect reports its outcome through a typed RPC.
+
+- `newProjectEnvelopeEventReceivedEndpointRunner(project, connectionName, routes)` opens the connection and each route's binding from the project configuration and wraps every target in the binding's durable project inbox, so an event is stored before Connect receives `200`. Mount `runner.serveHTTP` at the Connect configuration's URL to Publish and run `runner.run(context)` for the life of the process; it replays pending inbox events first. Wire targets with `newDexRPCTriggerTarget` or `newDexFlowTriggerTarget` from `@superdurable/connectors-sdk`. `runner.runningSourceCount()` serves a readiness check.
+- The endpoint accepts only `POST` up to `connectMaxBodyBytes` (`413` above it, before the signature is checked), and accepts any `X-DocuSign-Signature-<n>` header equal to the base64 HMAC-SHA256 of the raw body under `connect_hmac_key`, with `"` removed from the key, in constant time. A bad signature or a body that is not a JSON SIM envelope event with GUID identities answers `400`. A connection without a key, a moment with no running binding, and a failed inbox write answer `503`, so Connect retries. Another Connect event, such as `recipient-completed`, and an outcome the binding's `events` filter excludes are acknowledged with `200` and not recorded.
+- The event ID is the lowercase envelope ID and the event name, such as `93be49ab-0000-0000-0000-f752070d71ec:envelope-completed`, so a Connect retry or a second configuration delivering the same outcome keeps one ID. `occurredAt` is Connect's `generatedDateTime`, or the receipt time when it is blank or unparsable. The payload carries the lowercase account ID, the envelope summary's lowercase `status`, `voidedReason`, and named text `customFields` when the configuration includes envelope data; `envelopeEventCustomFieldValue` reads one field.
+- The binding configuration is `{"events": [...]}` with distinct values from the three outcomes; empty or omitted records all three. The connector declares no Studio units, so `defineEnvelopeEventReceivedTriggerBinding` needs no `configurationUI` and Dex Web saves the binding as `{}`.
+- `envelopeEventReceivedWebhookEndpoint(connection)` and `newEnvelopeEventReceivedTrigger` build the same endpoint and a standalone runner without the project inbox; every Trigger of one connection shares one endpoint.
+
+The unit tests mirror the Go endpoint tests for signatures, forgeries, filters, oversized and XML bodies, a missing key, and the inbox. The integration test runs the example against a real Dex Server with a local DocuSign stand-in: it refuses a forged delivery, consumes an uncorrelated one, resumes the Flow once from a signed outcome and its redelivery, skips a filtered outcome, and replays an inbox event recorded before a restart. Live DocuSign Connect deliveries have not been verified for this package.

package/dex-connector.json

@@ -4,13 +4,15 @@
   "package": {
     "ecosystem": "npm",
     "name": "@superdurable/connector-docusign",
-    "version": "0.1.0"
+    "version": "0.2.0"
   },
   "factories": [
     {
       "name": "newCreateEnvelopeFromTemplateStep",
       "kind": "mutation",
       "operationId": "createEnvelopeFromTemplate",
+      "inputType": "CreateEnvelopeFromTemplateInput",
+      "description": "Create one envelope from a server template, filling its roles in their routing order, and send it or keep it as a draft. DocuSign has no idempotency key, so the call runs with sync durability, tags the envelope with a hidden custom field derived from the Step's idempotency key, and on every later attempt looks for that envelope by the field before sending again; an outcome it cannot confirm selects uncertain.",
       "fields": {
         "stepType": "stepType",
         "annotations": "annotations",
@@ -38,12 +40,107 @@
           "field": "defect",
           "optional": true
         }
-      ]
+      ],
+      "inputSchema": {
+        "$defs": {
+          "EnvelopeCustomField": {
+            "additionalProperties": false,
+            "description": "EnvelopeCustomField is one envelope text custom field, hidden from recipients, such as a correlation ID that a Connect event carries back.",
+            "properties": {
+              "name": {
+                "description": "Name is the field name, 1 to 50 characters.",
+                "type": "string"
+              },
+              "value": {
+                "description": "Value is the field value, at most 100 characters.",
+                "type": "string"
+              }
+            },
+            "required": [
+              "name",
+              "value"
+            ],
+            "type": "object"
+          },
+          "TemplateRole": {
+            "additionalProperties": false,
+            "description": "TemplateRole assigns one person to a template role.",
+            "properties": {
+              "email": {
+                "description": "Email is the recipient's email address, at most 100 characters.",
+                "type": "string"
+              },
+              "name": {
+                "description": "Name is the recipient's full name, 1 to 100 characters.",
+                "type": "string"
+              },
+              "roleName": {
+                "description": "RoleName is the template's role name, such as Customer, matched as DocuSign matches it.",
+                "type": "string"
+              },
+              "routingOrder": {
+                "description": "RoutingOrder overrides the role's routing order, 1 to 999; zero keeps the template's order, which decides who is asked to sign first.",
+                "type": "integer"
+              }
+            },
+            "required": [
+              "email",
+              "name",
+              "roleName"
+            ],
+            "type": "object"
+          }
+        },
+        "additionalProperties": false,
+        "description": "CreateEnvelopeFromTemplateInput describes one envelope created from a DocuSign server template.",
+        "properties": {
+          "customFields": {
+            "description": "CustomFields adds hidden text custom fields, at most 10, such as a correlation ID that Connect events return. Names are 1 to 50 characters and unique; dexIdempotencyKey is reserved.",
+            "items": {
+              "$ref": "#/$defs/EnvelopeCustomField"
+            },
+            "type": "array"
+          },
+          "emailBlurb": {
+            "description": "EmailBlurb overrides the template's email message, at most 10,000 characters; blank keeps it.",
+            "type": "string"
+          },
+          "emailSubject": {
+            "description": "EmailSubject overrides the template's email subject, at most 100 characters; blank keeps it.",
+            "type": "string"
+          },
+          "isDraft": {
+            "description": "IsDraft creates the envelope with status created and sends nothing; false sends it at once.",
+            "type": "boolean"
+          },
+          "templateId": {
+            "description": "TemplateID is the server template's GUID, shown in DocuSign under Templates > the template > Template ID.",
+            "type": "string"
+          },
+          "templateRoles": {
+            "description": "TemplateRoles fills the template's roles by name, 1 to 100 of them. Every role the template requires must be filled.",
+            "items": {
+              "$ref": "#/$defs/TemplateRole"
+            },
+            "type": [
+              "array",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "templateId",
+          "templateRoles"
+        ],
+        "type": "object"
+      }
     },
     {
       "name": "newGetEnvelopeStep",
       "kind": "query",
       "operationId": "getEnvelope",
+      "inputType": "GetEnvelopeInput",
+      "description": "Read one envelope's status, status timestamps, void reason, and text custom fields. DocuSign allows an app one status read per envelope every 15 minutes, so prefer the envelopeEventReceived Trigger and poll only as a fallback.",
       "fields": {
         "stepType": "stepType",
         "annotations": "annotations",
@@ -76,12 +173,28 @@
           "field": "defect",
           "optional": true
         }
-      ]
+      ],
+      "inputSchema": {
+        "additionalProperties": false,
+        "description": "GetEnvelopeInput names the envelope to read.",
+        "properties": {
+          "envelopeId": {
+            "description": "EnvelopeID is the envelope's GUID, such as a createEnvelopeFromTemplate Result's envelopeId.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "envelopeId"
+        ],
+        "type": "object"
+      }
     },
     {
       "name": "newListEnvelopeRecipientsStep",
       "kind": "query",
       "operationId": "listEnvelopeRecipients",
+      "inputType": "ListEnvelopeRecipientsInput",
+      "description": "List an envelope's recipients in routing order with each one's type, role, status, and sent, delivered, signed, and declined times, and the routing order DocuSign is currently waiting on.",
       "fields": {
         "stepType": "stepType",
         "annotations": "annotations",
@@ -114,12 +227,28 @@
           "field": "defect",
           "optional": true
         }
-      ]
+      ],
+      "inputSchema": {
+        "additionalProperties": false,
+        "description": "ListEnvelopeRecipientsInput names the envelope whose recipients to list.",
+        "properties": {
+          "envelopeId": {
+            "description": "EnvelopeID is the envelope's GUID.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "envelopeId"
+        ],
+        "type": "object"
+      }
     },
     {
       "name": "newVoidEnvelopeStep",
       "kind": "mutation",
       "operationId": "voidEnvelope",
+      "inputType": "VoidEnvelopeInput",
+      "description": "Void one sent or delivered envelope with a reason, the compensation for a send that must not complete. An envelope that is already voided also selects voided, so a repeated call is safe; a completed, declined, or draft envelope selects notVoidable with its status.",
       "fields": {
         "stepType": "stepType",
         "annotations": "annotations",
@@ -157,12 +286,33 @@
           "field": "defect",
           "optional": true
         }
-      ]
+      ],
+      "inputSchema": {
+        "additionalProperties": false,
+        "description": "VoidEnvelopeInput names the envelope to void and why.",
+        "properties": {
+          "envelopeId": {
+            "description": "EnvelopeID is the envelope's GUID.",
+            "type": "string"
+          },
+          "voidedReason": {
+            "description": "VoidedReason is shown to the recipients, 1 to 200 characters, such as \"Signing deadline passed\".",
+            "type": "string"
+          }
+        },
+        "required": [
+          "envelopeId",
+          "voidedReason"
+        ],
+        "type": "object"
+      }
     },
     {
       "name": "newDownloadCombinedDocumentStep",
       "kind": "query",
       "operationId": "downloadCombinedDocument",
+      "inputType": "DownloadCombinedDocumentInput",
+      "description": "Stream an envelope's documents as one combined PDF, optionally with the certificate of completion, through a SHA-256 digest and into the application's CombinedDocumentStore when one is configured. The Result holds the byte count, digest, and the store's location, never the PDF bytes.",
       "fields": {
         "stepType": "stepType",
         "annotations": "annotations",
@@ -200,7 +350,35 @@
           "field": "defect",
           "optional": true
         }
-      ]
+      ],
+      "inputSchema": {
+        "additionalProperties": false,
+        "description": "DownloadCombinedDocumentInput names the envelope whose documents to download.",
+        "properties": {
+          "envelopeId": {
+            "description": "EnvelopeID is the envelope's GUID, normally of a completed envelope.",
+            "type": "string"
+          },
+          "includeCertificate": {
+            "description": "IncludeCertificate appends DocuSign's certificate of completion to the combined PDF.",
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "envelopeId"
+        ],
+        "type": "object"
+      }
+    },
+    {
+      "name": "defineEnvelopeEventReceivedTriggerBinding",
+      "kind": "trigger",
+      "triggerName": "envelopeEventReceived",
+      "fields": {
+        "connectionName": "connectionName",
+        "bindingName": "bindingName",
+        "configurationUI": "configurationUI"
+      }
     }
   ]
 }

package/dist/{chunk-42O7OZRV.js → chunk-PSJGBNG4.js}

@@ -212,7 +212,9 @@ var CreateEnvelopeFromTemplateDefinition = {
     { id: "uncertain", description: "The create request was sent but DocuSign's answer was lost, a server error, or unreadable, and no envelope with this Step's custom field could be found, so an envelope may exist that this Result does not name; do not create another automatically.", optional: true },
     { id: "defect", description: "Local input, connection configuration, or connector definition is invalid.", optional: true }
   ],
-  stepDefaults: { executeMethodTimeoutMs: 6e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 6e4, maximumAttempts: 6, totalDurationMs: 39e5 } }
+  stepDefaults: { executeMethodTimeoutMs: 6e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 6e4, maximumAttempts: 6, totalDurationMs: 39e5 } },
+  repeatOnUnknown: "limited",
+  maxSends: 3
 };
 var CreateEnvelopeFromTemplateMetadata = { kind: "mutation", idempotency: "required", authorization: "required" };
 var GetEnvelopeBranch = {
@@ -287,7 +289,9 @@ var VoidEnvelopeDefinition = {
     { id: "invalidResponse", description: "DocuSign returned a malformed or oversized response.", optional: true },
     { id: "defect", description: "Local input, connection configuration, or connector definition is invalid.", optional: true }
   ],
-  stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "async", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 6e4, maximumAttempts: 0, totalDurationMs: 39e5 } }
+  stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "async", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 6e4, maximumAttempts: 0, totalDurationMs: 39e5 } },
+  repeatOnUnknown: "limited",
+  maxSends: 3
 };
 var VoidEnvelopeMetadata = { kind: "mutation", idempotency: "required", authorization: "required" };
 var DownloadCombinedDocumentBranch = {

package/dist/{connection-YEptevxS.d.ts → connection-BFvLyRgn.d.ts}

@@ -360,4 +360,4 @@ declare function newConnection(client: Operations, reference: ConnectionRef): Co
 /** Bind scripted operations to a named connection. */
 declare function newConnectionWithOperations(operations: Operations, reference: ConnectionRef): Connection;
 
-export { newConnectionWithOperations as A, type CreateEnvelopeFromTemplateInput as C, type DownloadCombinedDocumentInput as D, type Envelope as E, type GetEnvelopeInput as G, type ListEnvelopeRecipientsInput as L, type Operations as O, type Recipient as R, type TemplateRole as T, type VoidEnvelopeInput as V, type CreatedEnvelope as a, Connection as b, type CombinedDocument as c, type EnvelopeRecipients as d, type VoidedEnvelope as e, type CredentialSource as f, type Config as g, type Credentials as h, CombinedDocumentSchema as i, ConfigSchema as j, CreateEnvelopeFromTemplateInputSchema as k, CreatedEnvelopeSchema as l, DownloadCombinedDocumentInputSchema as m, type EnvelopeCustomField as n, EnvelopeCustomFieldSchema as o, EnvelopeRecipientsSchema as p, EnvelopeSchema as q, GetEnvelopeInputSchema as r, ListEnvelopeRecipientsInputSchema as s, RecipientSchema as t, TemplateRoleSchema as u, VoidEnvelopeInputSchema as v, VoidedEnvelopeSchema as w, decodeCredentials as x, decodeSharedCredentials as y, newConnection as z };
+export { newConnectionWithOperations as A, type CreateEnvelopeFromTemplateInput as C, type DownloadCombinedDocumentInput as D, type Envelope as E, type GetEnvelopeInput as G, type ListEnvelopeRecipientsInput as L, type Operations as O, type Recipient as R, type TemplateRole as T, type VoidEnvelopeInput as V, type CreatedEnvelope as a, Connection as b, type CombinedDocument as c, type EnvelopeRecipients as d, type VoidedEnvelope as e, type CredentialSource as f, type Credentials as g, type Config as h, type EnvelopeCustomField as i, CombinedDocumentSchema as j, ConfigSchema as k, CreateEnvelopeFromTemplateInputSchema as l, CreatedEnvelopeSchema as m, DownloadCombinedDocumentInputSchema as n, EnvelopeCustomFieldSchema as o, EnvelopeRecipientsSchema as p, EnvelopeSchema as q, GetEnvelopeInputSchema as r, ListEnvelopeRecipientsInputSchema as s, RecipientSchema as t, TemplateRoleSchema as u, VoidEnvelopeInputSchema as v, VoidedEnvelopeSchema as w, decodeCredentials as x, decodeSharedCredentials as y, newConnection as z };

package/dist/index.d.ts

@@ -1,11 +1,14 @@
-import { C as CreateEnvelopeFromTemplateInput, a as CreatedEnvelope, b as Connection, D as DownloadCombinedDocumentInput, c as CombinedDocument, G as GetEnvelopeInput, E as Envelope, L as ListEnvelopeRecipientsInput, d as EnvelopeRecipients, V as VoidEnvelopeInput, e as VoidedEnvelope, f as CredentialSource, g as Config, h as Credentials, O as Operations } from './connection-YEptevxS.js';
-export { i as CombinedDocumentSchema, j as ConfigSchema, k as CreateEnvelopeFromTemplateInputSchema, l as CreatedEnvelopeSchema, m as DownloadCombinedDocumentInputSchema, n as EnvelopeCustomField, o as EnvelopeCustomFieldSchema, p as EnvelopeRecipientsSchema, q as EnvelopeSchema, r as GetEnvelopeInputSchema, s as ListEnvelopeRecipientsInputSchema, R as Recipient, t as RecipientSchema, T as TemplateRole, u as TemplateRoleSchema, v as VoidEnvelopeInputSchema, w as VoidedEnvelopeSchema, x as decodeCredentials, y as decodeSharedCredentials, z as newConnection, A as newConnectionWithOperations } from './connection-YEptevxS.js';
+import { C as CreateEnvelopeFromTemplateInput, a as CreatedEnvelope, b as Connection, D as DownloadCombinedDocumentInput, c as CombinedDocument, G as GetEnvelopeInput, E as Envelope, L as ListEnvelopeRecipientsInput, d as EnvelopeRecipients, V as VoidEnvelopeInput, e as VoidedEnvelope, f as CredentialSource, g as Credentials, h as Config, O as Operations, i as EnvelopeCustomField } from './connection-BFvLyRgn.js';
+export { j as CombinedDocumentSchema, k as ConfigSchema, l as CreateEnvelopeFromTemplateInputSchema, m as CreatedEnvelopeSchema, n as DownloadCombinedDocumentInputSchema, o as EnvelopeCustomFieldSchema, p as EnvelopeRecipientsSchema, q as EnvelopeSchema, r as GetEnvelopeInputSchema, s as ListEnvelopeRecipientsInputSchema, R as Recipient, t as RecipientSchema, T as TemplateRole, u as TemplateRoleSchema, v as VoidEnvelopeInputSchema, w as VoidedEnvelopeSchema, x as decodeCredentials, y as decodeSharedCredentials, z as newConnection, A as newConnectionWithOperations } from './connection-BFvLyRgn.js';
 import * as _superdurable_connectors_sdk from '@superdurable/connectors-sdk';
-import { MutationDefinition, QueryDefinition, MutationStepConfig, Mutation, MutationResult, QueryStepConfig, Query, QueryResult, MutationStep, QueryStep, Call, QueryAttempt, MutationAttempt, Failure, ReceiptDraft } from '@superdurable/connectors-sdk';
+import { MutationDefinition, QueryDefinition, MutationStepConfig, Mutation, MutationResult, QueryStepConfig, Query, QueryResult, MutationStep, QueryStep, Call, QueryAttempt, MutationAttempt, TriggerLogger, Failure, ReceiptDraft, TriggerEvent, TriggerTarget, TriggerRunner, TriggerContext, ConnectorConfigurationUI, TriggerDefinition, TriggerBindingDefinition } from '@superdurable/connectors-sdk';
 import { StepTarget } from '@superdurable/dex';
-import { LoadedProject } from '@superdurable/connectors-sdk/projectconfig';
+import { LoadedProject, TriggerInboxKey, Configuration } from '@superdurable/connectors-sdk/projectconfig';
 import { ProviderRequest, ProviderResponse } from '@superdurable/connectors-sdk/providerhttp';
-import 'zod';
+import { ManifestCredentialRefreshDriver } from '@superdurable/connectors-sdk/oauthtoken';
+import { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http';
+import { z } from 'zod';
+import { WebhookEndpoint } from '@superdurable/connectors-sdk/webhooktrigger';
 
 /** Stable connector identity. */
 declare const ConnectorID = "docusign";
@@ -259,7 +262,7 @@ declare class CreateEnvelopeFromTemplateOperation implements Mutation<CreateEnve
     /** Bind the authenticated DocuSign client. */
     constructor(client: DocuSignClient);
     /** Return manifest routes and Execute defaults. */
-    definition(): _superdurable_connectors_sdk.QueryDefinition;
+    definition(): _superdurable_connectors_sdk.MutationDefinition;
     /** Use the stable Dex Call ID as the hidden deduplication marker. */
     idempotencyKey(callId: string): string;
     /** Invoke one safe-to-classify create attempt. */
@@ -291,7 +294,7 @@ declare class VoidEnvelopeOperation implements Mutation<VoidEnvelopeInput, Voide
     /** Bind the authenticated DocuSign client. */
     constructor(client: DocuSignClient);
     /** Return manifest routes and Execute defaults. */
-    definition(): _superdurable_connectors_sdk.QueryDefinition;
+    definition(): _superdurable_connectors_sdk.MutationDefinition;
     /** Use the stable Call ID for this safely repeatable PUT. */
     idempotencyKey(callId: string): string;
     /** Invoke one void attempt. */
@@ -327,6 +330,8 @@ interface DocuSignClientOptions {
     now?: () => Date;
     /** Persist a combined PDF outside Dex payloads. */
     documentStore?: CombinedDocumentStore;
+    /** Receive the envelopeEventReceived Trigger's delivery records; omitted uses the SDK's console logger. */
+    logger?: TriggerLogger;
 }
 /** One provider answer; oversized applies only to successful JSON bodies. */
 interface DocuSignResponse {
@@ -363,12 +368,17 @@ declare class DocuSignClient {
     readonly maxResponseBytes: number;
     readonly maxDocumentBytes: number;
     readonly documentStore: CombinedDocumentStore | undefined;
+    /** Largest Connect request body the envelopeEventReceived endpoint accepts. */
+    readonly connectMaxBodyBytes: number;
+    /** Destination of the envelopeEventReceived Trigger's records. */
+    readonly triggerLogger: TriggerLogger;
     private readonly accountId;
     private readonly send;
     private readonly hasCustomSend;
     private readonly now;
     private readonly accountCache;
-    private readonly refreshDriver;
+    /** @internal Refreshes expiring OAuth credentials for operations and the Connect endpoint. */
+    readonly refreshDriver: ManifestCredentialRefreshDriver<Credentials>;
     /** Validate connection settings and bind host-owned renewable credentials. */
     constructor(config: Config, credentials: CredentialSource, options?: DocuSignClientOptions);
     /** Bind the template creation Mutation. */
@@ -399,4 +409,145 @@ declare class DocuSignClient {
 /** Open a named DocuSign connection with generated private and shared credential decoders. */
 declare function newProjectConnection(project: LoadedProject, connectionName: string, options?: DocuSignClientOptions): Connection<Operations>;
 
-export { CombinedDocument, type CombinedDocumentReference, type CombinedDocumentStore, Config, Connection, ConnectorID, CreateEnvelopeFromTemplateBranch, CreateEnvelopeFromTemplateBranchCreated, CreateEnvelopeFromTemplateBranchDefect, CreateEnvelopeFromTemplateBranchProviderRejected, CreateEnvelopeFromTemplateBranchUncertain, CreateEnvelopeFromTemplateDefinition, CreateEnvelopeFromTemplateInput, CreateEnvelopeFromTemplateMetadata, CreateEnvelopeFromTemplateOperation, type CreateEnvelopeFromTemplateStepConfig, CreatedEnvelope, CredentialSource, Credentials, DocuSignClient, type DocuSignClientOptions, DownloadCombinedDocumentBranch, DownloadCombinedDocumentBranchDefect, DownloadCombinedDocumentBranchDownloaded, DownloadCombinedDocumentBranchInvalidResponse, DownloadCombinedDocumentBranchNotFound, DownloadCombinedDocumentBranchProviderRejected, DownloadCombinedDocumentBranchTooLarge, DownloadCombinedDocumentDefinition, DownloadCombinedDocumentInput, DownloadCombinedDocumentMetadata, DownloadCombinedDocumentOperation, type DownloadCombinedDocumentStepConfig, Envelope, EnvelopeRecipients, GetEnvelopeBranch, GetEnvelopeBranchDefect, GetEnvelopeBranchFound, GetEnvelopeBranchInvalidResponse, GetEnvelopeBranchNotFound, GetEnvelopeBranchProviderRejected, GetEnvelopeDefinition, GetEnvelopeInput, GetEnvelopeMetadata, GetEnvelopeOperation, type GetEnvelopeStepConfig, ListEnvelopeRecipientsBranch, ListEnvelopeRecipientsBranchDefect, ListEnvelopeRecipientsBranchInvalidResponse, ListEnvelopeRecipientsBranchListed, ListEnvelopeRecipientsBranchNotFound, ListEnvelopeRecipientsBranchProviderRejected, ListEnvelopeRecipientsDefinition, ListEnvelopeRecipientsInput, ListEnvelopeRecipientsMetadata, ListEnvelopeRecipientsOperation, type ListEnvelopeRecipientsStepConfig, ProviderID, VoidEnvelopeBranch, VoidEnvelopeBranchDefect, VoidEnvelopeBranchInvalidResponse, VoidEnvelopeBranchNotFound, VoidEnvelopeBranchNotVoidable, VoidEnvelopeBranchProviderRejected, VoidEnvelopeBranchVoided, VoidEnvelopeDefinition, VoidEnvelopeInput, VoidEnvelopeMetadata, VoidEnvelopeOperation, type VoidEnvelopeStepConfig, VoidedEnvelope, newCreateEnvelopeFromTemplateStep, newDownloadCombinedDocumentStep, newGetEnvelopeStep, newListEnvelopeRecipientsStep, newProjectConnection, newVoidEnvelopeStep };
+/** The Connect event sent when every recipient finished. */
+declare const ConnectEventEnvelopeCompleted = "envelope-completed";
+/** The Connect event sent when a recipient declined. */
+declare const ConnectEventEnvelopeDeclined = "envelope-declined";
+/** The Connect event sent when the sender voided the envelope or it expired. */
+declare const ConnectEventEnvelopeVoided = "envelope-voided";
+/** The Connect events the envelopeEventReceived Trigger records. */
+declare const ConnectEnvelopeEvents: readonly string[];
+/** One envelope Connect event name. */
+type ConnectEnvelopeEvent = typeof ConnectEventEnvelopeCompleted | typeof ConnectEventEnvelopeDeclined | typeof ConnectEventEnvelopeVoided;
+/**
+ * Filters the Connect events one binding records. An empty or omitted events list records every
+ * envelope-completed, envelope-declined, and envelope-voided event. It reduces what a binding stores; the
+ * application's TriggerFilter remains its admission rule.
+ */
+declare const EnvelopeEventReceivedTriggerConfigurationSchema: z.ZodObject<{
+    events: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
+/** Event filter of one envelopeEventReceived binding. */
+type EnvelopeEventReceivedTriggerConfiguration = z.infer<typeof EnvelopeEventReceivedTriggerConfigurationSchema>;
+/**
+ * One HMAC-verified Connect envelope event in the JSON SIM format; field names and order match the Go
+ * connector. Its Trigger event ID is the envelope ID and the event name, such as
+ * 93be49ab-0000-0000-0000-f752070d71ec:envelope-completed, so a Connect retry or a second Connect
+ * configuration delivering the same outcome keeps one ID.
+ */
+interface EnvelopeEvent {
+    /** envelope-completed, envelope-declined, or envelope-voided. */ event: string;
+    /** The envelope's lowercase GUID. */ envelopeId: string;
+    /** The sender's lowercase DocuSign API account GUID. */ accountId: string;
+    /** When Connect generated the message, or when the endpoint received it if Connect left it blank, as RFC 3339 UTC. */ generatedAt: string;
+    /** The envelope summary's lowercase status; absent unless the Connect configuration includes envelope data. */ status?: Envelope['status'];
+    /** The envelope summary's void reason for an envelope-voided event, when included. */ voidedReason?: string;
+    /** The envelope's text custom fields; absent unless the Connect configuration's Include Data lists Custom Fields. */ customFields?: EnvelopeCustomField[];
+}
+/** Runtime validator of a replayed EnvelopeEvent payload. */
+declare const EnvelopeEventSchema: z.ZodPipe<z.ZodObject<{
+    event: z.ZodString;
+    envelopeId: z.ZodString;
+    accountId: z.ZodString;
+    generatedAt: z.ZodString;
+    status: z.ZodOptional<z.ZodString>;
+    voidedReason: z.ZodOptional<z.ZodString>;
+    customFields: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodTransform<EnvelopeEvent, {
+    event: string;
+    envelopeId: string;
+    accountId: string;
+    generatedAt: string;
+    status?: string | undefined;
+    voidedReason?: string | undefined;
+    customFields?: {
+        name: string;
+        value: string;
+    }[] | undefined;
+}>>;
+/** Return the value of the event's named text custom field, or undefined when it has none. */
+declare function envelopeEventCustomFieldValue(event: EnvelopeEvent, name: string): string | undefined;
+/** A Connect message that is not a JSON SIM envelope event with GUID identities. */
+declare class ConnectMessageMalformedError extends Error {
+    constructor();
+}
+/** No X-DocuSign-Signature-N header matches the HMAC-SHA256 of the body. */
+declare class ConnectSignatureInvalidError extends Error {
+    constructor();
+}
+/** Accept any X-DocuSign-Signature-N whose standard base64 equals the body's HMAC-SHA256 under hmacKey. */
+declare function verifyConnectSignature(body: Uint8Array, headers: IncomingHttpHeaders, hmacKey: string): void;
+/**
+ * Decode a JSON SIM envelope outcome received at receivedAt. Another valid Connect event returns
+ * undefined, so the endpoint acknowledges it unrecorded; anything else throws ConnectMessageMalformedError.
+ */
+declare function decodeConnectMessage(body: Uint8Array, receivedAt: Date): TriggerEvent<EnvelopeEvent> | undefined;
+
+/** Manifest definition of envelopeEventReceived. */
+declare const EnvelopeEventReceivedTriggerDefinition: TriggerDefinition;
+/** One static application binding of envelopeEventReceived. */
+interface EnvelopeEventReceivedTriggerBindingConfig {
+    /** Static connection name. */ connectionName: string;
+    /** Static binding name. */ bindingName: string;
+    /** Optional Connector Studio configuration units; the connector declares none, so Dex Web saves the binding as {}, which records all three outcomes. */ configurationUI?: ConnectorConfigurationUI;
+}
+/** Declare a static envelopeEventReceived binding for Flow Definition tooling and Dex Web. */
+declare function defineEnvelopeEventReceivedTriggerBinding(config: EnvelopeEventReceivedTriggerBindingConfig): TriggerBindingDefinition;
+/** Configuration of one standalone envelopeEventReceived Trigger. */
+interface EnvelopeEventReceivedTriggerConfig {
+    /** DocuSign connection from newProjectConnection or newConnection with a DocuSignClient. */ connection: Connection;
+    /** Static connection name; must equal the connection's name. */ connectionName: string;
+    /** Static binding name. */ bindingName: string;
+    /** The binding's event filter. */ configuration: EnvelopeEventReceivedTriggerConfiguration;
+    /** Routes accepted events into the application. */ target: TriggerTarget<EnvelopeEvent>;
+}
+/**
+ * Create one envelopeEventReceived Trigger fed by the connection's shared Connect endpoint, which
+ * envelopeEventReceivedWebhookEndpoint returns for the application to mount. Every Trigger of one
+ * connection shares that endpoint. Throws a TypeError or the schema's error on invalid wiring.
+ */
+declare function newEnvelopeEventReceivedTrigger(config: EnvelopeEventReceivedTriggerConfig): TriggerRunner;
+/**
+ * Return the connection's Connect endpoint, creating it on first use, for an application to mount at the
+ * URL to Publish of its Connect configuration. Every envelopeEventReceived Trigger built from this
+ * connection feeds from it. It answers 503 while none of them runs and without a connect_hmac_key, so
+ * Connect retries; 400 for a bad signature or a body that is not JSON SIM; 413 above connectMaxBodyBytes,
+ * before the signature is checked; and 200 for another Connect event, unrecorded.
+ */
+declare function envelopeEventReceivedWebhookEndpoint(connection: Connection): WebhookEndpoint<Credentials, EnvelopeEvent>;
+/** One envelopeEventReceived binding from the project configuration and its application target. */
+interface ProjectEnvelopeEventReceivedTriggerRoute {
+    /** Configured binding name whose configuration filters the events. */ bindingName: string;
+    /** Receives the binding's events through its durable project inbox, such as a newDexRPCTriggerTarget that resumes the waiting Flow. */ target: TriggerTarget<EnvelopeEvent>;
+}
+/**
+ * Serves one connection's Connect endpoint while running its bindings. Mount serveHTTP at the Connect
+ * configuration's URL to Publish and run it for the life of the process. It is safe for concurrent requests.
+ */
+declare class EnvelopeEventReceivedEndpointRunner {
+    #private;
+    /** @internal Use newProjectEnvelopeEventReceivedEndpointRunner. */
+    constructor(endpoint: WebhookEndpoint<Credentials, EnvelopeEvent>, runners: readonly TriggerRunner[]);
+    /** Verify, record, and acknowledge one Connect delivery. It answers 503 until run has replayed every binding's pending events and started receiving, so Connect retries. */
+    serveHTTP(request: IncomingMessage, response: ServerResponse): Promise<void>;
+    /** Replay each binding's durable inbox, then deliver new events until the context ends, rejecting with TriggerDeliveryAbortedError, or a binding fails. */
+    run(context: TriggerContext): Promise<void>;
+    /** How many bindings are receiving events; a readiness check can wait until it equals the number of routes. */
+    runningSourceCount(): number;
+}
+/**
+ * Open connectionName and every route's binding from the loaded project and wrap each target in the
+ * binding's durable project inbox, so an event is stored before Connect receives 200. A route whose
+ * binding is not configured throws ObjectNotFoundError; an invalid configuration, a blank or duplicated
+ * binding name, or no routes throws. The client options' logger also applies to the inboxes.
+ */
+declare function newProjectEnvelopeEventReceivedEndpointRunner(project: LoadedProject, connectionName: string, routes: readonly ProjectEnvelopeEventReceivedTriggerRoute[], options?: DocuSignClientOptions): EnvelopeEventReceivedEndpointRunner;
+/** Wraps one binding's target so each event is stored before its acknowledgement. */
+type DurableEnvelopeEventReceivedTarget = (key: TriggerInboxKey, target: TriggerTarget<EnvelopeEvent>) => TriggerTarget<EnvelopeEvent>;
+/** @internal Run routes on connection with the bindings that configuration stores, wrapping each target with makeDurable. */
+declare function newEnvelopeEventReceivedEndpointRunner(connection: Connection, configuration: Configuration, routes: readonly ProjectEnvelopeEventReceivedTriggerRoute[], makeDurable: DurableEnvelopeEventReceivedTarget): EnvelopeEventReceivedEndpointRunner;
+
+export { CombinedDocument, type CombinedDocumentReference, type CombinedDocumentStore, Config, type ConnectEnvelopeEvent, ConnectEnvelopeEvents, ConnectEventEnvelopeCompleted, ConnectEventEnvelopeDeclined, ConnectEventEnvelopeVoided, ConnectMessageMalformedError, ConnectSignatureInvalidError, Connection, ConnectorID, CreateEnvelopeFromTemplateBranch, CreateEnvelopeFromTemplateBranchCreated, CreateEnvelopeFromTemplateBranchDefect, CreateEnvelopeFromTemplateBranchProviderRejected, CreateEnvelopeFromTemplateBranchUncertain, CreateEnvelopeFromTemplateDefinition, CreateEnvelopeFromTemplateInput, CreateEnvelopeFromTemplateMetadata, CreateEnvelopeFromTemplateOperation, type CreateEnvelopeFromTemplateStepConfig, CreatedEnvelope, CredentialSource, Credentials, DocuSignClient, type DocuSignClientOptions, DownloadCombinedDocumentBranch, DownloadCombinedDocumentBranchDefect, DownloadCombinedDocumentBranchDownloaded, DownloadCombinedDocumentBranchInvalidResponse, DownloadCombinedDocumentBranchNotFound, DownloadCombinedDocumentBranchProviderRejected, DownloadCombinedDocumentBranchTooLarge, DownloadCombinedDocumentDefinition, DownloadCombinedDocumentInput, DownloadCombinedDocumentMetadata, DownloadCombinedDocumentOperation, type DownloadCombinedDocumentStepConfig, type DurableEnvelopeEventReceivedTarget, Envelope, EnvelopeCustomField, type EnvelopeEvent, EnvelopeEventReceivedEndpointRunner, type EnvelopeEventReceivedTriggerBindingConfig, type EnvelopeEventReceivedTriggerConfig, type EnvelopeEventReceivedTriggerConfiguration, EnvelopeEventReceivedTriggerConfigurationSchema, EnvelopeEventReceivedTriggerDefinition, EnvelopeEventSchema, EnvelopeRecipients, GetEnvelopeBranch, GetEnvelopeBranchDefect, GetEnvelopeBranchFound, GetEnvelopeBranchInvalidResponse, GetEnvelopeBranchNotFound, GetEnvelopeBranchProviderRejected, GetEnvelopeDefinition, GetEnvelopeInput, GetEnvelopeMetadata, GetEnvelopeOperation, type GetEnvelopeStepConfig, ListEnvelopeRecipientsBranch, ListEnvelopeRecipientsBranchDefect, ListEnvelopeRecipientsBranchInvalidResponse, ListEnvelopeRecipientsBranchListed, ListEnvelopeRecipientsBranchNotFound, ListEnvelopeRecipientsBranchProviderRejected, ListEnvelopeRecipientsDefinition, ListEnvelopeRecipientsInput, ListEnvelopeRecipientsMetadata, ListEnvelopeRecipientsOperation, type ListEnvelopeRecipientsStepConfig, type ProjectEnvelopeEventReceivedTriggerRoute, ProviderID, VoidEnvelopeBranch, VoidEnvelopeBranchDefect, VoidEnvelopeBranchInvalidResponse, VoidEnvelopeBranchNotFound, VoidEnvelopeBranchNotVoidable, VoidEnvelopeBranchProviderRejected, VoidEnvelopeBranchVoided, VoidEnvelopeDefinition, VoidEnvelopeInput, VoidEnvelopeMetadata, VoidEnvelopeOperation, type VoidEnvelopeStepConfig, VoidedEnvelope, decodeConnectMessage, defineEnvelopeEventReceivedTriggerBinding, envelopeEventCustomFieldValue, envelopeEventReceivedWebhookEndpoint, newCreateEnvelopeFromTemplateStep, newDownloadCombinedDocumentStep, newEnvelopeEventReceivedEndpointRunner, newEnvelopeEventReceivedTrigger, newGetEnvelopeStep, newListEnvelopeRecipientsStep, newProjectConnection, newProjectEnvelopeEventReceivedEndpointRunner, newVoidEnvelopeStep, verifyConnectSignature };

package/dist/index.js

@@ -63,7 +63,7 @@ import {
   newConnectionWithOperations,
   newProjectConnection,
   newProjectCredentialProvider
-} from "./chunk-42O7OZRV.js";
+} from "./chunk-PSJGBNG4.js";
 
 // src/generated/steps.ts
 import { goToBranch, newMutationStep, newQueryStep } from "@superdurable/connectors-sdk";
@@ -128,7 +128,7 @@ function newDownloadCombinedDocumentStep(configuration) {
 import { createHash as createHash2 } from "crypto";
 import { BodyTooLargeError, isHeaderSafeCredential, parseRetryAfter, readErrorTokens, sendProviderRequest } from "@superdurable/connectors-sdk/providerhttp";
 import { ManifestCredentialRefreshDriver } from "@superdurable/connectors-sdk/oauthtoken";
-import { resolveCredential, resolveCredentialAfterRejection } from "@superdurable/connectors-sdk";
+import { defaultTriggerLogger, resolveCredential, resolveCredentialAfterRejection } from "@superdurable/connectors-sdk";
 
 // src/generated/refresh.ts
 var Authorization = {
@@ -185,7 +185,8 @@ var Authorization = {
             "invalid_client",
             "invalid_grant",
             "unauthorized_client"
-          ]
+          ],
+          "tokenExchangeTimeout": "25s"
         },
         "scopes": [
           "signature",
@@ -247,7 +248,8 @@ var Authorization = {
             "invalid_client",
             "invalid_grant",
             "unauthorized_client"
-          ]
+          ],
+          "tokenExchangeTimeout": "25s"
         },
         "scopes": [
           "signature",
@@ -631,11 +633,11 @@ function buildCreateBody(input, marker) {
   if ((input.customFields?.length ?? 0) > 10) throw new Error("customFields holds at most 10 fields");
   const fields = [{ name: "dexIdempotencyKey", value: marker, show: "false", required: "false" }];
   const fieldNames = /* @__PURE__ */ new Set(["dexidempotencykey"]);
-  for (const [index, field] of (input.customFields ?? []).entries()) {
-    if (!field.name || [...field.name].length > 50 || [...field.value].length > 100) throw new Error(`customFields[${index}] needs a 1 to 50 character name and a value of at most 100 characters`);
-    if (fieldNames.has(field.name.toLowerCase())) throw new Error(`customFields[${index}]: name ${JSON.stringify(field.name)} is reserved or repeated`);
-    fieldNames.add(field.name.toLowerCase());
-    fields.push({ name: field.name, value: field.value, show: "false", required: "false" });
+  for (const [index, field2] of (input.customFields ?? []).entries()) {
+    if (!field2.name || [...field2.name].length > 50 || [...field2.value].length > 100) throw new Error(`customFields[${index}] needs a 1 to 50 character name and a value of at most 100 characters`);
+    if (fieldNames.has(field2.name.toLowerCase())) throw new Error(`customFields[${index}]: name ${JSON.stringify(field2.name)} is reserved or repeated`);
+    fieldNames.add(field2.name.toLowerCase());
+    fields.push({ name: field2.name, value: field2.value, show: "false", required: "false" });
   }
   return { templateId: input.templateId.toLowerCase(), status: input.isDraft ? "created" : "sent", ...input.emailSubject ? { emailSubject: input.emailSubject } : {}, ...input.emailBlurb ? { emailBlurb: input.emailBlurb } : {}, templateRoles: roles, customFields: { textCustomFields: fields } };
 }
@@ -696,11 +698,11 @@ function decodeEnvelope(body) {
     if (typeof fields !== "object" || Array.isArray(fields)) throw new Error(malformed);
     const text = fields.textCustomFields;
     if (text != null && !Array.isArray(text)) throw new Error(malformed);
-    const customFields = (text ?? []).map((field) => {
-      if (!field || typeof field !== "object" || Array.isArray(field)) throw new Error(malformed);
-      const item = field;
+    const customFields = (text ?? []).map((field2) => {
+      if (!field2 || typeof field2 !== "object" || Array.isArray(field2)) throw new Error(malformed);
+      const item = field2;
       return { name: optionalString(item.name), value: optionalString(item.value) };
-    }).filter((field) => field.name);
+    }).filter((field2) => field2.name);
     if (customFields.length) result.customFields = customFields;
   }
   return result;
@@ -829,7 +831,7 @@ function recoveryRequestTimeout(call) {
 function findTagged(body, marker) {
   const raw = parseObject(body);
   if (raw.envelopes != null && !Array.isArray(raw.envelopes)) throw new Error(malformed);
-  return (raw.envelopes ?? []).map((entry) => decodeEnvelope(Buffer.from(JSON.stringify(entry)))).filter((envelope) => envelope.customFields?.some((field) => field.name === "dexIdempotencyKey" && field.value === marker)).map((envelope) => ({ envelopeId: envelope.envelopeId, status: envelope.status, ...envelope.statusChangedAt ? { statusChangedAt: envelope.statusChangedAt } : {} }));
+  return (raw.envelopes ?? []).map((entry) => decodeEnvelope(Buffer.from(JSON.stringify(entry)))).filter((envelope) => envelope.customFields?.some((field2) => field2.name === "dexIdempotencyKey" && field2.value === marker)).map((envelope) => ({ envelopeId: envelope.envelopeId, status: envelope.status, ...envelope.statusChangedAt ? { statusChangedAt: envelope.statusChangedAt } : {} }));
 }
 
 // src/client.ts
@@ -838,6 +840,7 @@ var productionHostPattern = /^(?!demo\.)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.do
 var maximumErrorBodyBytes = 65536;
 var defaultResponseBytes = 1048576;
 var defaultDocumentBytes = 67108864;
+var defaultConnectBodyBytes = 2097152;
 var rateLimitCodes = /* @__PURE__ */ new Set([
   "HOURLY_APIINVOCATION_LIMIT_EXCEEDED",
   "BURST_APIINVOCATION_LIMIT_EXCEEDED",
@@ -884,20 +887,27 @@ var DocuSignClient2 = class {
     if (!Number.isSafeInteger(this.maxResponseBytes) || this.maxResponseBytes <= 0) throw new TypeError("maxResponseBytes must be positive");
     if (!Number.isSafeInteger(this.maxDocumentBytes) || this.maxDocumentBytes <= 0) throw new TypeError("maxDocumentBytes must be positive");
     if (config.connectMaxBodyBytes !== void 0 && (!Number.isSafeInteger(config.connectMaxBodyBytes) || config.connectMaxBodyBytes < 0)) throw new TypeError("connectMaxBodyBytes must be non-negative");
+    this.connectMaxBodyBytes = config.connectMaxBodyBytes || defaultConnectBodyBytes;
     this.send = options.send ?? sendProviderRequest;
     this.hasCustomSend = options.send !== void 0;
     this.now = options.now ?? (() => /* @__PURE__ */ new Date());
     this.documentStore = options.documentStore;
+    this.triggerLogger = options.logger ?? defaultTriggerLogger;
   }
   credentials;
   maxResponseBytes;
   maxDocumentBytes;
   documentStore;
+  /** Largest Connect request body the envelopeEventReceived endpoint accepts. */
+  connectMaxBodyBytes;
+  /** Destination of the envelopeEventReceived Trigger's records. */
+  triggerLogger;
   accountId;
   send;
   hasCustomSend;
   now;
   accountCache = /* @__PURE__ */ new Map();
+  /** @internal Refreshes expiring OAuth credentials for operations and the Connect endpoint. */
   refreshDriver = new ManifestCredentialRefreshDriver({ providerName: "DocuSign", auth: Authorization, credentialFields: CredentialFields });
   /** Bind the template creation Mutation. */
   createEnvelopeFromTemplate() {
@@ -1192,9 +1202,260 @@ function newProjectConnection2(project, connectionName, options = {}) {
     return new DocuSignClient2(config, newProjectCredentialProvider(loadedProject, name, decodeCredentials, encodeCredentials, decodeSharedCredentials), options);
   });
 }
+
+// src/connect_event.ts
+import { createHmac, timingSafeEqual } from "crypto";
+import { z } from "zod";
+var ConnectEventEnvelopeCompleted = "envelope-completed";
+var ConnectEventEnvelopeDeclined = "envelope-declined";
+var ConnectEventEnvelopeVoided = "envelope-voided";
+var ConnectEnvelopeEvents = [ConnectEventEnvelopeCompleted, ConnectEventEnvelopeDeclined, ConnectEventEnvelopeVoided];
+var EnvelopeEventReceivedTriggerConfigurationSchema = z.strictObject({
+  /** envelope-completed, envelope-declined, and envelope-voided; empty accepts all three. */
+  events: z.array(z.string()).nullish()
+}).superRefine((configuration, context) => {
+  const events = configuration.events ?? [];
+  if (events.some((event) => !ConnectEnvelopeEvents.includes(event)) || new Set(events).size !== events.length) {
+    context.addIssue({ code: "custom", message: `envelopeEventReceived events must be distinct values from ${ConnectEnvelopeEvents.join(", ")}` });
+  }
+});
+var EnvelopeEventSchema = z.object({
+  event: z.string(),
+  envelopeId: z.string(),
+  accountId: z.string(),
+  generatedAt: z.string(),
+  status: z.string().optional(),
+  voidedReason: z.string().optional(),
+  customFields: z.array(z.object({ name: z.string(), value: z.string() })).optional()
+}).transform((value) => value);
+function envelopeEventCustomFieldValue(event, name) {
+  return event.customFields?.find((field2) => field2.name === name)?.value;
+}
+var ConnectMessageMalformedError = class extends Error {
+  constructor() {
+    super("DocuSign returned a malformed response");
+    this.name = "ConnectMessageMalformedError";
+  }
+};
+var ConnectSignatureInvalidError = class extends Error {
+  constructor() {
+    super("no X-DocuSign-Signature header matches the HMAC-SHA256 of the body");
+    this.name = "ConnectSignatureInvalidError";
+  }
+};
+var signatureHeaderPattern = /^x-docusign-signature-([0-9]+)$/;
+var base64Pattern = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+function verifyConnectSignature(body, headers, hmacKey) {
+  const expected = createHmac("sha256", hmacKey).update(body).digest();
+  for (const [name, raw] of Object.entries(headers)) {
+    const suffix = signatureHeaderPattern.exec(name.toLowerCase())?.[1];
+    if (suffix === void 0 || Number(suffix) > 65535 || raw === void 0) continue;
+    for (const value of (Array.isArray(raw) ? raw : [raw]).flatMap((entry) => entry.split(","))) {
+      const encoded = value.trim();
+      if (!base64Pattern.test(encoded)) continue;
+      const signature = Buffer.from(encoded, "base64");
+      if (signature.length === expected.length && timingSafeEqual(signature, expected)) return;
+    }
+  }
+  throw new ConnectSignatureInvalidError();
+}
+function decodeConnectMessage(body, receivedAt) {
+  let message;
+  try {
+    message = JSON.parse(Buffer.from(body).toString("utf8"));
+  } catch {
+    throw new ConnectMessageMalformedError();
+  }
+  const root = objectOrNull(message);
+  const eventName = stringField(root, "event");
+  const data = objectOrNull(field(root, "data"));
+  const generatedDateTime = stringField(root, "generatedDateTime");
+  if (eventName === "" || data === null) throw new ConnectMessageMalformedError();
+  const accountId = stringField(data, "accountId");
+  const envelopeId = stringField(data, "envelopeId");
+  const summary = field(data, "envelopeSummary");
+  if (!ConnectEnvelopeEvents.includes(eventName)) return void 0;
+  if (!isGuid(envelopeId) || !isGuid(accountId)) throw new ConnectMessageMalformedError();
+  const event = { event: eventName, envelopeId: envelopeId.toLowerCase(), accountId: accountId.toLowerCase(), generatedAt: goTimestamp2(receivedAt) };
+  if (generatedDateTime !== "") {
+    try {
+      event.generatedAt = parseDocuSignTimestamp(generatedDateTime);
+    } catch {
+    }
+  }
+  if (summary !== null && typeof summary === "object" && !Array.isArray(summary)) {
+    const status = stringField(summary, "status").toLowerCase();
+    const voidedReason = stringField(summary, "voidedReason");
+    const customFields = textCustomFields(objectOrNull(field(summary, "customFields")));
+    if (status !== "") event.status = status;
+    if (voidedReason !== "") event.voidedReason = voidedReason;
+    if (customFields.length > 0) event.customFields = customFields;
+  }
+  return { id: `${event.envelopeId}:${event.event}`, occurredAt: new Date(event.generatedAt), payload: event };
+}
+function textCustomFields(fields) {
+  const raw = field(fields, "textCustomFields");
+  if (raw === null || raw === void 0) return [];
+  if (!Array.isArray(raw)) throw new ConnectMessageMalformedError();
+  const converted = [];
+  for (const entry of raw) {
+    const customField = objectOrNull(entry);
+    const name = stringField(customField, "name");
+    const value = stringField(customField, "value");
+    if (name !== "") converted.push({ name, value });
+  }
+  return converted;
+}
+function field(object, name) {
+  if (object === null) return void 0;
+  let found;
+  for (const [key, value] of Object.entries(object)) if (key === name || key.toLowerCase() === name.toLowerCase()) found = value;
+  return found;
+}
+function stringField(object, name) {
+  const value = field(object, name);
+  if (value === void 0 || value === null) return "";
+  if (typeof value !== "string") throw new ConnectMessageMalformedError();
+  return value;
+}
+function objectOrNull(value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) throw new ConnectMessageMalformedError();
+  return value;
+}
+function goTimestamp2(value) {
+  return value.toISOString().replace(/\.([0-9]*?)0*Z$/, (_match, fraction) => fraction ? `.${fraction}Z` : "Z");
+}
+
+// src/trigger.ts
+import {
+  mustTriggerBindingDefinition,
+  newTrigger
+} from "@superdurable/connectors-sdk";
+import { ObjectNotFoundError, decodeTriggerConfiguration, newDurableTriggerTarget, parseTriggerPayloadJSON } from "@superdurable/connectors-sdk/projectconfig";
+import { WebhookEndpoint, WebhookEndpointRunner, WebhookVerificationUnavailableError } from "@superdurable/connectors-sdk/webhooktrigger";
+var EnvelopeEventReceivedTriggerDefinition = {
+  trigger: { connectorId: ConnectorID, triggerName: "envelopeEventReceived" },
+  description: "Receive an HMAC-verified DocuSign Connect envelope-completed, envelope-declined, or envelope-voided event in the JSON SIM format, with the envelope ID and event name as its event ID and the envelope's text custom fields for correlation."
+};
+function defineEnvelopeEventReceivedTriggerBinding(config) {
+  return mustTriggerBindingDefinition({ definition: EnvelopeEventReceivedTriggerDefinition, ...config });
+}
+function newEnvelopeEventReceivedTrigger(config) {
+  const client = docuSignClientOf(config.connection);
+  if (config.connectionName !== config.connection.reference.name) {
+    throw new TypeError(`docusign connector trigger connectionName "${config.connectionName}" must equal its connection's name "${config.connection.reference.name}"`);
+  }
+  const configuration = EnvelopeEventReceivedTriggerConfigurationSchema.parse(config.configuration);
+  const events = configuration.events ?? [];
+  const source = envelopeEventReceivedWebhookEndpoint(config.connection).newSource((event) => events.length === 0 || events.includes(event.payload.event));
+  return newTrigger({
+    definition: EnvelopeEventReceivedTriggerDefinition,
+    source,
+    target: config.target,
+    logger: client.triggerLogger,
+    binding: { connection: config.connection.reference, trigger: EnvelopeEventReceivedTriggerDefinition.trigger, name: config.bindingName }
+  });
+}
+function envelopeEventReceivedWebhookEndpoint(connection) {
+  const client = docuSignClientOf(connection);
+  let endpoints = webhookEndpointsByClient.get(client);
+  if (!endpoints) {
+    endpoints = /* @__PURE__ */ new Map();
+    webhookEndpointsByClient.set(client, endpoints);
+  }
+  const key = `${connection.reference.provider}\0${connection.reference.name}`;
+  let endpoint = endpoints.get(key);
+  if (!endpoint) {
+    endpoint = newConnectEndpoint(client, connection.reference);
+    endpoints.set(key, endpoint);
+  }
+  return endpoint;
+}
+var EnvelopeEventReceivedEndpointRunner = class {
+  #runner;
+  #endpoint;
+  /** @internal Use newProjectEnvelopeEventReceivedEndpointRunner. */
+  constructor(endpoint, runners) {
+    this.#endpoint = endpoint;
+    this.#runner = new WebhookEndpointRunner(endpoint, runners);
+  }
+  /** Verify, record, and acknowledge one Connect delivery. It answers 503 until run has replayed every binding's pending events and started receiving, so Connect retries. */
+  serveHTTP(request, response) {
+    return this.#runner.serveHTTP(request, response);
+  }
+  /** Replay each binding's durable inbox, then deliver new events until the context ends, rejecting with TriggerDeliveryAbortedError, or a binding fails. */
+  run(context) {
+    return this.#runner.run(context);
+  }
+  /** How many bindings are receiving events; a readiness check can wait until it equals the number of routes. */
+  runningSourceCount() {
+    return this.#endpoint.runningSourceCount();
+  }
+};
+function newProjectEnvelopeEventReceivedEndpointRunner(project, connectionName, routes, options = {}) {
+  const connection = newProjectConnection2(project, connectionName, options);
+  const client = docuSignClientOf(connection);
+  return newEnvelopeEventReceivedEndpointRunner(connection, project.configuration, routes, (key, target) => newDurableTriggerTarget(project.triggerInbox(key), key, target, {
+    logger: client.triggerLogger,
+    decodePayload: (_payloadJSON, payloadBytes) => EnvelopeEventSchema.parse(parseTriggerPayloadJSON(payloadBytes))
+  }));
+}
+function newEnvelopeEventReceivedEndpointRunner(connection, configuration, routes, makeDurable) {
+  if (!routes || routes.length === 0) throw new TypeError("DocuSign envelopeEventReceived routes are required");
+  const endpoint = envelopeEventReceivedWebhookEndpoint(connection);
+  const connectionName = connection.reference.name;
+  const triggerName = EnvelopeEventReceivedTriggerDefinition.trigger.triggerName;
+  const bindingNames = /* @__PURE__ */ new Set();
+  const runners = routes.map((route) => {
+    const bindingName = route?.bindingName?.trim();
+    if (!bindingName || !route.target) throw new TypeError("DocuSign envelopeEventReceived binding name and target are required");
+    if (bindingNames.has(bindingName)) throw new TypeError(`DocuSign envelopeEventReceived binding name "${bindingName}" is duplicated`);
+    bindingNames.add(bindingName);
+    const key = { connectorId: ConnectorID, connectionName, triggerName, bindingName };
+    let bindingConfiguration;
+    try {
+      bindingConfiguration = decodeTriggerConfiguration(configuration, key, EnvelopeEventReceivedTriggerConfigurationSchema);
+    } catch (error) {
+      if (error instanceof ObjectNotFoundError) throw error;
+      throw new Error(`DocuSign envelopeEventReceived binding "${bindingName}" configuration: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    return newEnvelopeEventReceivedTrigger({ connection, connectionName, bindingName, configuration: bindingConfiguration, target: makeDurable(key, route.target) });
+  });
+  return new EnvelopeEventReceivedEndpointRunner(endpoint, runners);
+}
+var webhookEndpointsByClient = /* @__PURE__ */ new WeakMap();
+function newConnectEndpoint(client, connection) {
+  return new WebhookEndpoint({
+    connectorId: ConnectorID,
+    triggerName: EnvelopeEventReceivedTriggerDefinition.trigger.triggerName,
+    connection,
+    credentials: client.credentials,
+    credentialRefresh: client.refreshDriver,
+    maxBodyBytes: client.connectMaxBodyBytes,
+    now: () => client.currentTime(),
+    logger: client.triggerLogger,
+    verifyRequest: async (request, credentials) => {
+      const hmacKey = (credentials.connectHmacKey?.reveal() ?? "").replaceAll('"', "");
+      if (hmacKey === "") throw new WebhookVerificationUnavailableError();
+      verifyConnectSignature(request.body, request.headers, hmacKey);
+    },
+    decodeEvent: (request) => decodeConnectMessage(request.body, request.receivedAt)
+  });
+}
+function docuSignClientOf(connection) {
+  if (!(connection?.operations instanceof DocuSignClient2)) throw new TypeError("DocuSign Triggers require a connection bound to a DocuSignClient");
+  return connection.operations;
+}
 export {
   CombinedDocumentSchema,
   ConfigSchema,
+  ConnectEnvelopeEvents,
+  ConnectEventEnvelopeCompleted,
+  ConnectEventEnvelopeDeclined,
+  ConnectEventEnvelopeVoided,
+  ConnectMessageMalformedError,
+  ConnectSignatureInvalidError,
   Connection,
   ConnectorID,
   CreateEnvelopeFromTemplateBranch,
@@ -1220,6 +1481,10 @@ export {
   DownloadCombinedDocumentMetadata,
   DownloadCombinedDocumentOperation,
   EnvelopeCustomFieldSchema,
+  EnvelopeEventReceivedEndpointRunner,
+  EnvelopeEventReceivedTriggerConfigurationSchema,
+  EnvelopeEventReceivedTriggerDefinition,
+  EnvelopeEventSchema,
   EnvelopeRecipientsSchema,
   EnvelopeSchema,
   GetEnvelopeBranch,
@@ -1257,14 +1522,22 @@ export {
   VoidEnvelopeMetadata,
   VoidEnvelopeOperation,
   VoidedEnvelopeSchema,
+  decodeConnectMessage,
   decodeCredentials,
   decodeSharedCredentials,
+  defineEnvelopeEventReceivedTriggerBinding,
+  envelopeEventCustomFieldValue,
+  envelopeEventReceivedWebhookEndpoint,
   newConnection,
   newConnectionWithOperations,
   newCreateEnvelopeFromTemplateStep,
   newDownloadCombinedDocumentStep,
+  newEnvelopeEventReceivedEndpointRunner,
+  newEnvelopeEventReceivedTrigger,
   newGetEnvelopeStep,
   newListEnvelopeRecipientsStep,
   newProjectConnection2 as newProjectConnection,
-  newVoidEnvelopeStep
+  newProjectEnvelopeEventReceivedEndpointRunner,
+  newVoidEnvelopeStep,
+  verifyConnectSignature
 };

package/dist/mock.d.ts

@@ -1,6 +1,6 @@
 import { MockMutation, MockQuery, Case } from '@superdurable/connectors-sdk/connectormock';
 import { Failure } from '@superdurable/connectors-sdk';
-import { O as Operations, b as Connection, C as CreateEnvelopeFromTemplateInput, a as CreatedEnvelope, G as GetEnvelopeInput, E as Envelope, L as ListEnvelopeRecipientsInput, d as EnvelopeRecipients, V as VoidEnvelopeInput, e as VoidedEnvelope, D as DownloadCombinedDocumentInput, c as CombinedDocument, n as EnvelopeCustomField, R as Recipient, T as TemplateRole } from './connection-YEptevxS.js';
+import { O as Operations, b as Connection, C as CreateEnvelopeFromTemplateInput, a as CreatedEnvelope, G as GetEnvelopeInput, E as Envelope, L as ListEnvelopeRecipientsInput, d as EnvelopeRecipients, V as VoidEnvelopeInput, e as VoidedEnvelope, D as DownloadCombinedDocumentInput, c as CombinedDocument, i as EnvelopeCustomField, R as Recipient, T as TemplateRole } from './connection-BFvLyRgn.js';
 import 'zod';
 
 /** Go zero value for TemplateRole in scripted cases. */

package/dist/mock.js

@@ -20,7 +20,7 @@ import {
   VoidEnvelopeInputSchema,
   VoidedEnvelopeSchema,
   newConnectionWithOperations
-} from "./chunk-42O7OZRV.js";
+} from "./chunk-PSJGBNG4.js";
 
 // src/generated/mock.ts
 import { branchCase, retryCase, uncertainCase, newMutation, newQuery } from "@superdurable/connectors-sdk/connectormock";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdurable/connector-docusign",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "DocuSign eSignature operations for Dex Flows",
   "repository": {
     "type": "git",
@@ -25,7 +25,8 @@
     "./mock": {
       "types": "./dist/mock.d.ts",
       "import": "./dist/mock.js"
-    }
+    },
+    "./dex-connector.json": "./dex-connector.json"
   },
   "files": [
     "dist",
@@ -41,10 +42,11 @@
     "test:integration": "npm run build && vitest run test/integration/*.integration.test.ts",
     "check": "npm test && npm run typecheck && npm run lint",
     "example:envelope": "npm run build && tsx examples/envelope-status/main.ts",
-    "example:envelope:start": "npm run build && tsx examples/envelope-status/start.ts"
+    "example:envelope:start": "npm run build && tsx examples/envelope-status/start.ts",
+    "example:outcome": "npm run build && tsx examples/envelope-outcome/main.ts"
   },
   "dependencies": {
-    "@superdurable/connectors-sdk": "0.7.0",
+    "@superdurable/connectors-sdk": "0.11.0",
     "@superdurable/dex": ">=1.28.0",
     "zod": "^4.1.0"
   },