@superdurable/connector-docusign 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Super Durable
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# DocuSign TypeScript connector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+The [envelope status example](examples/envelope-status/README.md) is a runnable Flow, Worker, and Client using the static `docusign-envelope-reader` connection. Its integration test runs through a real Dex Worker and Client with a local DocuSign stand-in. Provider replay scenarios under [`conformance/connectors/docusign`](../../../conformance/connectors/docusign/) check Go and TypeScript request and classification parity. Real DocuSign OAuth authorization, regional account lookup, eSignature requests, and Connect configuration require verification in Dex Web with a user-controlled provider account; they were not exercised by these local tests.
+
+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

@@ -0,0 +1,384 @@
+{
+  "connectorId": "docusign",
+  "releaseTag": "connectors/docusign/go/v0.24.0",
+  "package": {
+    "ecosystem": "npm",
+    "name": "@superdurable/connector-docusign",
+    "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",
+        "connectionName": "connectionName",
+        "resultAttribute": "resultAttribute"
+      },
+      "branches": [
+        {
+          "id": "created",
+          "field": "created",
+          "optional": false
+        },
+        {
+          "id": "providerRejected",
+          "field": "providerRejected",
+          "optional": true
+        },
+        {
+          "id": "uncertain",
+          "field": "uncertain",
+          "optional": true
+        },
+        {
+          "id": "defect",
+          "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",
+        "connectionName": "connectionName",
+        "resultAttribute": "resultAttribute"
+      },
+      "branches": [
+        {
+          "id": "found",
+          "field": "found",
+          "optional": false
+        },
+        {
+          "id": "notFound",
+          "field": "notFound",
+          "optional": true
+        },
+        {
+          "id": "providerRejected",
+          "field": "providerRejected",
+          "optional": true
+        },
+        {
+          "id": "invalidResponse",
+          "field": "invalidResponse",
+          "optional": true
+        },
+        {
+          "id": "defect",
+          "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",
+        "connectionName": "connectionName",
+        "resultAttribute": "resultAttribute"
+      },
+      "branches": [
+        {
+          "id": "listed",
+          "field": "listed",
+          "optional": false
+        },
+        {
+          "id": "notFound",
+          "field": "notFound",
+          "optional": true
+        },
+        {
+          "id": "providerRejected",
+          "field": "providerRejected",
+          "optional": true
+        },
+        {
+          "id": "invalidResponse",
+          "field": "invalidResponse",
+          "optional": true
+        },
+        {
+          "id": "defect",
+          "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",
+        "connectionName": "connectionName",
+        "resultAttribute": "resultAttribute"
+      },
+      "branches": [
+        {
+          "id": "voided",
+          "field": "voided",
+          "optional": false
+        },
+        {
+          "id": "notVoidable",
+          "field": "notVoidable",
+          "optional": true
+        },
+        {
+          "id": "notFound",
+          "field": "notFound",
+          "optional": true
+        },
+        {
+          "id": "providerRejected",
+          "field": "providerRejected",
+          "optional": true
+        },
+        {
+          "id": "invalidResponse",
+          "field": "invalidResponse",
+          "optional": true
+        },
+        {
+          "id": "defect",
+          "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",
+        "connectionName": "connectionName",
+        "resultAttribute": "resultAttribute"
+      },
+      "branches": [
+        {
+          "id": "downloaded",
+          "field": "downloaded",
+          "optional": false
+        },
+        {
+          "id": "notFound",
+          "field": "notFound",
+          "optional": true
+        },
+        {
+          "id": "tooLarge",
+          "field": "tooLarge",
+          "optional": true
+        },
+        {
+          "id": "providerRejected",
+          "field": "providerRejected",
+          "optional": true
+        },
+        {
+          "id": "invalidResponse",
+          "field": "invalidResponse",
+          "optional": true
+        },
+        {
+          "id": "defect",
+          "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"
+      }
+    }
+  ]
+}