@signature-kit/documenso 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,22 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.0
4
+
5
+ - Documenso now owns its envelope props, attributes, state schema, schema names,
6
+ and retained no-op diff instead of using core remote-signature contracts.
7
+ - Treat failed envelope distribution as still `draft` with `not_distributed`
8
+ provider status instead of reporting it as sent.
9
+ - Limit distribute rollback deletion to unambiguous pre-effect 4xx failures
10
+ (except 408, 409, and 429); response-shape errors, 5xxs, and timeouts no
11
+ longer delete possibly live envelopes.
12
+ - Accept missing recipient `signingUrl` values in create, get, and list responses.
13
+ - Add offline local-HTTP-server coverage for Documenso provider behavior in the
14
+ default test suite.
15
+
16
+ Breaking: request props now use `DocumensoEnvelopeProps` with `contentBase64`
17
+ documents, and `getDocumensoSignatureRequest` / `listDocumensoSignatureRequests`
18
+ return `DocumensoEnvelope` instead of core `RemoteSignature*` types.
19
+
3
20
  ## 0.2.0
4
21
 
5
22
  - Download signed documents via the envelope item id (previously passed the envelope id and
@@ -11,4 +28,4 @@
11
28
 
12
29
  - Initial npm-ready release for `@signature-kit/documenso`.
13
30
  - Published package metadata, MIT license, README, and package-local changelog.
14
- - Ships alchemy v2 remote-signature provider for Documenso envelope creation, lookup, deletion, and signed-document download.
31
+ - Ships an Alchemy v2 remote-signature provider for Documenso envelope creation, lookup, deletion, and signed-document download.
package/README.md CHANGED
@@ -1,24 +1,81 @@
1
1
  # @signature-kit/documenso
2
2
 
3
- Alchemy v2 remote-signature provider for Documenso envelope creation, lookup, deletion, and signed-document download.
3
+ Alchemy v2 remote-signature provider for Documenso envelope creation, lookup, listing, cancellation, deletion, and completed-document download.
4
4
 
5
5
  ## Install
6
6
 
7
7
  ```sh
8
- bun add @signature-kit/documenso effect alchemy
8
+ bun add @signature-kit/documenso @signature-kit/http effect alchemy
9
9
  ```
10
10
 
11
- ## Exports
11
+ `effect` and `alchemy` are direct runtime dependencies. Provide `signatureHttpClientLive` at the stack boundary; `providers(options)` supplies only Documenso credentials and resource providers.
12
12
 
13
- - `@signature-kit/documenso`
13
+ ## Public surface
14
14
 
15
- ## Runtime model
15
+ - `@signature-kit/documenso` — Documenso envelope/document/recipient schemas, `DocumensoSignatureRequest`, `DocumensoProviders`, `providers`, `getDocumensoSignatureRequest`, `listDocumensoSignatureRequests`, `cancelDocumensoSignatureRequest`, `deleteDocumensoSignatureRequest`, and `downloadDocumensoSignedDocument`.
16
16
 
17
- SignatureKit packages are Effect-native. Public APIs return typed `Effect.Effect` values; recoverable faults stay in the typed error channel; callers provide required services and layers explicitly at the application boundary.
17
+ Capability matrix:
18
18
 
19
- ## Version
19
+ | Capability | Supported |
20
+ | -------------------------------- | ------------------------------------------------------------------------- |
21
+ | Create retained Alchemy envelope | Yes |
22
+ | Get envelope | Yes |
23
+ | List envelopes | Yes |
24
+ | Cancel envelope | Yes |
25
+ | Delete envelope | Yes |
26
+ | Download signed document | Yes, after the envelope is completed and an envelope item id is available |
20
27
 
21
- Current npm release line: `0.1.0`.
28
+ Retained-resource semantics: Alchemy `reconcile` creates once and returns cached output on subsequent plans; provider `list` returns `[]`; `nuke` is skipped. Multi-step create rollback deletes remote state only after unambiguous pre-effect 4xx failures, excluding 408, 409, 429, 5xx, timeouts, and response-shape failures.
29
+
30
+ ## Example
31
+
32
+ ```ts
33
+ import * as Alchemy from "alchemy";
34
+ import {
35
+ DocumensoSignatureRequest,
36
+ downloadDocumensoSignedDocument,
37
+ providers as documensoProviders,
38
+ type DocumensoProviderOptions,
39
+ } from "@signature-kit/documenso";
40
+ import { signatureHttpClientLive } from "@signature-kit/http";
41
+ import { Effect, Layer, Redacted } from "effect";
42
+
43
+ declare const pdfBase64: string;
44
+ declare const apiKey: string;
45
+
46
+ const options: DocumensoProviderOptions = {
47
+ apiKey: Redacted.make(apiKey),
48
+ };
49
+
50
+ export default class Contracts extends Alchemy.Stack<Contracts>()(
51
+ "Contracts",
52
+ {
53
+ providers: Layer.merge(documensoProviders(options), signatureHttpClientLive),
54
+ state: Alchemy.inMemoryState(),
55
+ },
56
+ Effect.gen(function* () {
57
+ return yield* DocumensoSignatureRequest("service-agreement", {
58
+ title: "Service agreement",
59
+ documents: [
60
+ { fileName: "contract.pdf", mimeType: "application/pdf", contentBase64: pdfBase64 },
61
+ ],
62
+ recipients: [{ name: "Ada Lovelace", email: "ada@example.com", role: "signer" }],
63
+ send: true,
64
+ });
65
+ }),
66
+ ) {}
67
+
68
+ export const downloadSigned = (envelopeId: string) =>
69
+ downloadDocumensoSignedDocument(options, envelopeId).pipe(
70
+ Effect.provide(signatureHttpClientLive),
71
+ );
72
+ ```
73
+
74
+ ## Errors and i18n
75
+
76
+ Invalid inputs, remote HTTP failures, unsupported operations, and invalid response shapes fail as `SignatureKitError` from `@signature-kit/signatures`. Applications can render localized copy through `errorMessage` from `@signature-kit/i18n` with the `signatureKitErrorMessages` catalog from `@signature-kit/signatures`.
77
+
78
+ Docs: <https://signaturekit.dev/en-US/docs/providers/documenso>.
22
79
 
23
80
  ## License
24
81
 
package/dist/index.d.ts CHANGED
@@ -1,9 +1,82 @@
1
- import { SignatureKitError } from "@signature-kit/core/config";
2
- import type { RemoteSignatureRequest, RemoteSignatureRequestProps } from "@signature-kit/core/config";
3
- import { SignatureHttpClient } from "@signature-kit/core/http";
1
+ import { SignatureKitError } from "@signature-kit/signatures";
2
+ import { SignatureHttpClient } from "@signature-kit/http";
4
3
  import { Resource } from "alchemy";
5
4
  import * as Provider from "alchemy/Provider";
6
5
  import { Context, Effect, Layer, Redacted, Schema } from "effect";
6
+ export declare const DocumensoProviderId = "documenso";
7
+ export declare const DocumensoEnvelopeStateSchema: Schema.Literals<readonly ["draft", "sent", "completed", "cancelled", "deleted", "declined", "expired"]>;
8
+ export type DocumensoEnvelopeState = (typeof DocumensoEnvelopeStateSchema)["Type"];
9
+ export declare const DocumensoEnvelopeDocumentSchema: Schema.Struct<{
10
+ readonly fileName: Schema.NonEmptyString;
11
+ readonly mimeType: Schema.NonEmptyString;
12
+ readonly content: Schema.Uint8Array;
13
+ }>;
14
+ export type DocumensoEnvelopeDocument = (typeof DocumensoEnvelopeDocumentSchema)["Type"];
15
+ export declare const DocumensoEnvelopeDocumentPropsSchema: Schema.Struct<{
16
+ readonly fileName: Schema.NonEmptyString;
17
+ readonly mimeType: Schema.NonEmptyString;
18
+ readonly contentBase64: Schema.ConstraintDecoder<string, never>;
19
+ }>;
20
+ export type DocumensoEnvelopeDocumentProps = (typeof DocumensoEnvelopeDocumentPropsSchema)["Type"];
21
+ export declare const DocumensoRecipientRoleSchema: Schema.Literals<readonly ["approver", "signer"]>;
22
+ export type DocumensoRecipientRole = (typeof DocumensoRecipientRoleSchema)["Type"];
23
+ export declare const DocumensoEnvelopeRecipientSchema: Schema.Struct<{
24
+ readonly name: Schema.NonEmptyString;
25
+ readonly email: Schema.NonEmptyString;
26
+ readonly role: Schema.optional<Schema.Literals<readonly ["approver", "signer"]>>;
27
+ readonly routingOrder: Schema.optional<Schema.Number>;
28
+ }>;
29
+ export type DocumensoEnvelopeRecipient = (typeof DocumensoEnvelopeRecipientSchema)["Type"];
30
+ export declare const DocumensoEnvelopeInputSchema: Schema.Struct<{
31
+ readonly title: Schema.NonEmptyString;
32
+ readonly subject: Schema.optional<Schema.NonEmptyString>;
33
+ readonly message: Schema.optional<Schema.NonEmptyString>;
34
+ readonly documents: Schema.NonEmptyArray<Schema.Struct<{
35
+ readonly fileName: Schema.NonEmptyString;
36
+ readonly mimeType: Schema.NonEmptyString;
37
+ readonly content: Schema.Uint8Array;
38
+ }>>;
39
+ readonly recipients: Schema.NonEmptyArray<Schema.Struct<{
40
+ readonly name: Schema.NonEmptyString;
41
+ readonly email: Schema.NonEmptyString;
42
+ readonly role: Schema.optional<Schema.Literals<readonly ["approver", "signer"]>>;
43
+ readonly routingOrder: Schema.optional<Schema.Number>;
44
+ }>>;
45
+ readonly send: Schema.optional<Schema.Boolean>;
46
+ readonly expiresAt: Schema.optional<Schema.Date>;
47
+ readonly redirectUrl: Schema.optional<Schema.NonEmptyString>;
48
+ }>;
49
+ export type DocumensoEnvelopeInput = (typeof DocumensoEnvelopeInputSchema)["Type"];
50
+ export declare const DocumensoEnvelopePropsSchema: Schema.Struct<{
51
+ readonly title: Schema.NonEmptyString;
52
+ readonly subject: Schema.optional<Schema.NonEmptyString>;
53
+ readonly message: Schema.optional<Schema.NonEmptyString>;
54
+ readonly documents: Schema.NonEmptyArray<Schema.Struct<{
55
+ readonly fileName: Schema.NonEmptyString;
56
+ readonly mimeType: Schema.NonEmptyString;
57
+ readonly contentBase64: Schema.ConstraintDecoder<string, never>;
58
+ }>>;
59
+ readonly recipients: Schema.NonEmptyArray<Schema.Struct<{
60
+ readonly name: Schema.NonEmptyString;
61
+ readonly email: Schema.NonEmptyString;
62
+ readonly role: Schema.optional<Schema.Literals<readonly ["approver", "signer"]>>;
63
+ readonly routingOrder: Schema.optional<Schema.Number>;
64
+ }>>;
65
+ readonly send: Schema.optional<Schema.Boolean>;
66
+ readonly expiresAt: Schema.optional<Schema.Date>;
67
+ readonly redirectUrl: Schema.optional<Schema.NonEmptyString>;
68
+ }>;
69
+ export type DocumensoEnvelopeProps = (typeof DocumensoEnvelopePropsSchema)["Type"];
70
+ export declare const DocumensoEnvelopeSchema: Schema.Struct<{
71
+ readonly provider: Schema.Literal<"documenso">;
72
+ readonly id: Schema.NonEmptyString;
73
+ readonly state: Schema.Literals<readonly ["draft", "sent", "completed", "cancelled", "deleted", "declined", "expired"]>;
74
+ readonly providerStatus: Schema.optional<Schema.String>;
75
+ readonly signingUrl: Schema.optional<Schema.String>;
76
+ readonly detailsUrl: Schema.optional<Schema.String>;
77
+ readonly downloadUrl: Schema.optional<Schema.String>;
78
+ }>;
79
+ export type DocumensoEnvelope = (typeof DocumensoEnvelopeSchema)["Type"];
7
80
  declare const DocumensoAuthorizationSchemeSchema: Schema.Literals<readonly ["raw", "bearer"]>;
8
81
  export type DocumensoAuthorizationScheme = (typeof DocumensoAuthorizationSchemeSchema)["Type"];
9
82
  export declare const DocumensoProviderOptionsSchema: Schema.Struct<{
@@ -12,7 +85,7 @@ export declare const DocumensoProviderOptionsSchema: Schema.Struct<{
12
85
  readonly authorizationScheme: Schema.optional<Schema.Literals<readonly ["raw", "bearer"]>>;
13
86
  }>;
14
87
  export type DocumensoProviderOptions = (typeof DocumensoProviderOptionsSchema)["Type"];
15
- export type DocumensoSignatureRequest = Resource<"SignatureKit.DocumensoSignatureRequest", RemoteSignatureRequestProps, RemoteSignatureRequest>;
88
+ export type DocumensoSignatureRequest = Resource<"SignatureKit.DocumensoSignatureRequest", DocumensoEnvelopeProps, DocumensoEnvelope>;
16
89
  export declare const DocumensoSignatureRequest: import("alchemy").ResourceClass<DocumensoSignatureRequest>;
17
90
  declare const DocumensoCredentials_base: Context.ServiceClass<DocumensoCredentials, "@signature-kit/documenso/Credentials", {
18
91
  readonly apiKey: Redacted.Redacted<string>;
@@ -27,8 +100,8 @@ declare const DocumensoProviders_base: Provider.ProviderCollection<DocumensoProv
27
100
  export declare class DocumensoProviders extends DocumensoProviders_base {
28
101
  }
29
102
  export declare const providers: (options: DocumensoProviderOptions) => Layer.Layer<DocumensoProviders, SignatureKitError, SignatureHttpClient>;
30
- export declare const getDocumensoSignatureRequest: (options: DocumensoProviderOptions, id: string) => Effect.Effect<RemoteSignatureRequest, SignatureKitError, SignatureHttpClient>;
31
- export declare const listDocumensoSignatureRequests: (options: DocumensoProviderOptions) => Effect.Effect<ReadonlyArray<RemoteSignatureRequest>, SignatureKitError, SignatureHttpClient>;
103
+ export declare const getDocumensoSignatureRequest: (options: DocumensoProviderOptions, id: string) => Effect.Effect<DocumensoEnvelope, SignatureKitError, SignatureHttpClient>;
104
+ export declare const listDocumensoSignatureRequests: (options: DocumensoProviderOptions) => Effect.Effect<ReadonlyArray<DocumensoEnvelope>, SignatureKitError, SignatureHttpClient>;
32
105
  export declare const cancelDocumensoSignatureRequest: (options: DocumensoProviderOptions, id: string) => Effect.Effect<void, SignatureKitError, SignatureHttpClient>;
33
106
  export declare const deleteDocumensoSignatureRequest: (options: DocumensoProviderOptions, id: string) => Effect.Effect<void, SignatureKitError, SignatureHttpClient>;
34
107
  export declare const downloadDocumensoSignedDocument: (options: DocumensoProviderOptions, envelopeId: string) => Effect.Effect<Uint8Array, SignatureKitError, SignatureHttpClient>;
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EAMlB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAEV,sBAAsB,EAEtB,2BAA2B,EAC5B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAqB,MAAM,0BAA0B,CAAC;AAElF,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAU,QAAQ,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAC;AASlF,QAAA,MAAM,kCAAkC,6CAAqC,CAAC;AAC9E,MAAM,MAAM,4BAA4B,GAAG,CAAC,OAAO,kCAAkC,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/F,eAAO,MAAM,8BAA8B;;;;EAIzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC;AAqDvF,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAC9C,wCAAwC,EACxC,2BAA2B,EAC3B,sBAAsB,CACvB,CAAC;AAEF,eAAO,MAAM,yBAAyB,4DAGrC,CAAC;;;;;;AACF,qBAAa,oBAAqB,SAAQ,yBAGC;CAAG;AAE9C,eAAO,MAAM,yBAAyB,GACpC,SAAS,wBAAwB,KAChC,KAAK,CAAC,KAAK,CAAC,oBAAoB,EAAE,iBAAiB,CAgBnD,CAAC;AAwWJ,eAAO,MAAM,iCAAiC,oHA4B3C,CAAC;;AAEJ,qBAAa,kBAAmB,SAAQ,uBAEvC;CAAG;AAEJ,eAAO,MAAM,SAAS,GAAI,SAAS,wBAAwB,4EAIxD,CAAC;AAEJ,eAAO,MAAM,4BAA4B,GACvC,SAAS,wBAAwB,EACjC,IAAI,MAAM,KACT,MAAM,CAAC,MAAM,CAAC,sBAAsB,EAAE,iBAAiB,EAAE,mBAAmB,CAiB3E,CAAC;AAEL,eAAO,MAAM,8BAA8B,GACzC,SAAS,wBAAwB,KAChC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,sBAAsB,CAAC,EAAE,iBAAiB,EAAE,mBAAmB,CAiB1F,CAAC;AAEL,eAAO,MAAM,+BAA+B,GAC1C,SAAS,wBAAwB,EACjC,IAAI,MAAM,KACT,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,mBAAmB,CAiBzD,CAAC;AAEL,eAAO,MAAM,+BAA+B,GAC1C,SAAS,wBAAwB,EACjC,IAAI,MAAM,KACT,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,mBAAmB,CAiBzD,CAAC;AAEL,eAAO,MAAM,+BAA+B,GAC1C,SAAS,wBAAwB,EACjC,YAAY,MAAM,KACjB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,iBAAiB,EAAE,mBAAmB,CAiB/D,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/dist/index.js CHANGED
@@ -1,9 +1,112 @@
1
- import { SignatureKitError, SignatureKitErrorCodeValue, SignatureKitOperationValue, SignatureKitSchemaNameValue, redactedStringSchema, remoteSignatureInputFromResourceProps, } from "@signature-kit/core/config";
2
- import { SignatureHttpClient, normalizedBaseUrl } from "@signature-kit/core/http";
1
+ import { SignatureKitError, SignatureKitErrorCodeValue, SignatureKitOperationValue, redactedStringSchema, } from "@signature-kit/signatures";
2
+ import { SignatureHttpClient, normalizedBaseUrl } from "@signature-kit/http";
3
3
  import { Resource } from "alchemy";
4
4
  import * as Provider from "alchemy/Provider";
5
- import { Context, Effect, Layer, Option, Redacted, Schema, Stream } from "effect";
6
- const PROVIDER = "documenso";
5
+ import { Context, Effect, Layer, Match, Option, Redacted, Schema, Stream } from "effect";
6
+ const DocumensoSchemaName = {
7
+ providerOptions: "DocumensoProviderOptions",
8
+ signatureRequestProps: "DocumensoEnvelopeProps",
9
+ createEnvelopeResult: "DocumensoCreateEnvelopeResult",
10
+ distributeEnvelopeResult: "DocumensoDistributeEnvelopeResult",
11
+ envelopeResult: "DocumensoEnvelopeResult",
12
+ envelopeListResult: "DocumensoEnvelopeListResult",
13
+ };
14
+ const DocumensoOperation = {
15
+ create: "documenso.create",
16
+ download: "documenso.download",
17
+ };
18
+ const base64String = Schema.String.check(Schema.isBase64());
19
+ export const DocumensoProviderId = "documenso";
20
+ const PROVIDER = DocumensoProviderId;
21
+ export const DocumensoEnvelopeStateSchema = Schema.Literals([
22
+ "draft",
23
+ "sent",
24
+ "completed",
25
+ "cancelled",
26
+ "deleted",
27
+ "declined",
28
+ "expired",
29
+ ]);
30
+ export const DocumensoEnvelopeDocumentSchema = Schema.Struct({
31
+ fileName: Schema.NonEmptyString,
32
+ mimeType: Schema.NonEmptyString,
33
+ content: Schema.Uint8Array,
34
+ });
35
+ export const DocumensoEnvelopeDocumentPropsSchema = Schema.Struct({
36
+ fileName: Schema.NonEmptyString,
37
+ mimeType: Schema.NonEmptyString,
38
+ contentBase64: base64String,
39
+ });
40
+ export const DocumensoRecipientRoleSchema = Schema.Literals(["approver", "signer"]);
41
+ export const DocumensoEnvelopeRecipientSchema = Schema.Struct({
42
+ name: Schema.NonEmptyString,
43
+ email: Schema.NonEmptyString,
44
+ role: Schema.optional(DocumensoRecipientRoleSchema),
45
+ routingOrder: Schema.optional(Schema.Number),
46
+ });
47
+ export const DocumensoEnvelopeInputSchema = Schema.Struct({
48
+ title: Schema.NonEmptyString,
49
+ subject: Schema.optional(Schema.NonEmptyString),
50
+ message: Schema.optional(Schema.NonEmptyString),
51
+ documents: Schema.NonEmptyArray(DocumensoEnvelopeDocumentSchema),
52
+ recipients: Schema.NonEmptyArray(DocumensoEnvelopeRecipientSchema),
53
+ send: Schema.optional(Schema.Boolean),
54
+ expiresAt: Schema.optional(Schema.Date),
55
+ redirectUrl: Schema.optional(Schema.NonEmptyString),
56
+ });
57
+ export const DocumensoEnvelopePropsSchema = Schema.Struct({
58
+ title: Schema.NonEmptyString,
59
+ subject: Schema.optional(Schema.NonEmptyString),
60
+ message: Schema.optional(Schema.NonEmptyString),
61
+ documents: Schema.NonEmptyArray(DocumensoEnvelopeDocumentPropsSchema),
62
+ recipients: Schema.NonEmptyArray(DocumensoEnvelopeRecipientSchema),
63
+ send: Schema.optional(Schema.Boolean),
64
+ expiresAt: Schema.optional(Schema.Date),
65
+ redirectUrl: Schema.optional(Schema.NonEmptyString),
66
+ });
67
+ export const DocumensoEnvelopeSchema = Schema.Struct({
68
+ provider: Schema.Literal(PROVIDER),
69
+ id: Schema.NonEmptyString,
70
+ state: DocumensoEnvelopeStateSchema,
71
+ providerStatus: Schema.optional(Schema.String),
72
+ signingUrl: Schema.optional(Schema.String),
73
+ detailsUrl: Schema.optional(Schema.String),
74
+ downloadUrl: Schema.optional(Schema.String),
75
+ });
76
+ const documensoSignatureRequestNoopDiff = { action: "noop" };
77
+ const documensoSignatureRequestDiff = ({ olds, }) => Effect.succeed(olds === undefined ? undefined : documensoSignatureRequestNoopDiff);
78
+ const documensoSignatureRequestInputFromProps = (props) => {
79
+ const [firstDocument, ...restDocuments] = props.documents;
80
+ return {
81
+ title: props.title,
82
+ documents: [
83
+ {
84
+ fileName: firstDocument.fileName,
85
+ mimeType: firstDocument.mimeType,
86
+ content: Uint8Array.fromBase64(firstDocument.contentBase64),
87
+ },
88
+ ...restDocuments.map((document) => ({
89
+ fileName: document.fileName,
90
+ mimeType: document.mimeType,
91
+ content: Uint8Array.fromBase64(document.contentBase64),
92
+ })),
93
+ ],
94
+ recipients: props.recipients,
95
+ ...(props.subject === undefined ? {} : { subject: props.subject }),
96
+ ...(props.message === undefined ? {} : { message: props.message }),
97
+ ...(props.send === undefined ? {} : { send: props.send }),
98
+ ...(props.expiresAt === undefined ? {} : { expiresAt: props.expiresAt }),
99
+ ...(props.redirectUrl === undefined ? {} : { redirectUrl: props.redirectUrl }),
100
+ };
101
+ };
102
+ const documensoSignatureRequestInputFromResourceProps = (props) => Schema.decodeUnknownEffect(DocumensoEnvelopePropsSchema)(props).pipe(Effect.mapError((issue) => new SignatureKitError({
103
+ code: SignatureKitErrorCodeValue.invalidInput,
104
+ retryable: false,
105
+ provider: PROVIDER,
106
+ operation: SignatureKitOperationValue.schemaDecode,
107
+ schemaName: DocumensoSchemaName.signatureRequestProps,
108
+ issueMessage: String(issue),
109
+ })), Effect.map(documensoSignatureRequestInputFromProps));
7
110
  const DOCUMENSO_PROVIDER_COLLECTION_ID = "@signature-kit/documenso/Providers";
8
111
  const DEFAULT_BASE_URL = "https://app.documenso.com/api/v2";
9
112
  const DOCUMENSO_LIST_FIRST_PAGE = 1;
@@ -24,7 +127,7 @@ const DocumensoRecipientResultSchema = Schema.Struct({
24
127
  email: Schema.String,
25
128
  role: Schema.String,
26
129
  signingOrder: Schema.optional(Schema.NullOr(Schema.Number)),
27
- signingUrl: Schema.String,
130
+ signingUrl: Schema.optional(Schema.String),
28
131
  });
29
132
  const DocumensoDistributeEnvelopeResultSchema = Schema.Struct({
30
133
  success: Schema.Boolean,
@@ -65,7 +168,7 @@ export const documensoCredentialsLayer = (options) => Layer.effect(DocumensoCred
65
168
  retryable: false,
66
169
  provider: PROVIDER,
67
170
  operation: SignatureKitOperationValue.schemaDecode,
68
- schemaName: SignatureKitSchemaNameValue.documensoProviderOptions,
171
+ schemaName: DocumensoSchemaName.providerOptions,
69
172
  issueMessage: String(issue),
70
173
  }))));
71
174
  const documensoBaseUrl = (options) => options.baseUrl === undefined ? DEFAULT_BASE_URL : normalizedBaseUrl(options.baseUrl);
@@ -123,7 +226,7 @@ const createEnvelope = (http, options, baseUrl, input) => http.requestJson({
123
226
  url: `${baseUrl}/envelope/create`,
124
227
  headers: { Authorization: documensoAuthorization(options) },
125
228
  body: createEnvelopeBody(input),
126
- }, DocumensoCreateEnvelopeResultSchema, SignatureKitSchemaNameValue.documensoCreateEnvelopeResult);
229
+ }, DocumensoCreateEnvelopeResultSchema, DocumensoSchemaName.createEnvelopeResult);
127
230
  const distributeEnvelope = (http, options, baseUrl, input, envelope) => http
128
231
  .requestJson({
129
232
  provider: PROVIDER,
@@ -134,42 +237,40 @@ const distributeEnvelope = (http, options, baseUrl, input, envelope) => http
134
237
  Authorization: documensoAuthorization(options),
135
238
  },
136
239
  body: JSON.stringify({ envelopeId: envelope.id, meta: requestMeta(input) }),
137
- }, DocumensoDistributeEnvelopeResultSchema, SignatureKitSchemaNameValue.documensoDistributeEnvelopeResult)
240
+ }, DocumensoDistributeEnvelopeResultSchema, DocumensoSchemaName.distributeEnvelopeResult)
138
241
  .pipe(Effect.map((result) => ({
139
242
  provider: PROVIDER,
140
243
  id: result.id,
141
- state: "sent",
244
+ // A failed distribution means recipients were never notified — surface
245
+ // the envelope as still-draft rather than pretending it was sent.
246
+ state: result.success ? "sent" : "draft",
142
247
  providerStatus: result.success ? "distributed" : "not_distributed",
143
248
  detailsUrl: `${baseUrl}/envelope/${documensoPathId(result.id)}`,
144
249
  ...(result.recipients[0]?.signingUrl === undefined
145
250
  ? {}
146
251
  : { signingUrl: result.recipients[0].signingUrl }),
147
252
  })));
253
+ const DocumensoEnvelopeStatusSchema = Schema.Literals([
254
+ "DRAFT",
255
+ "PENDING",
256
+ "PROCESSING",
257
+ "SENT",
258
+ "SIGNED",
259
+ "COMPLETED",
260
+ "CLOSED",
261
+ "REJECTED",
262
+ "DECLINED",
263
+ "CANCELED",
264
+ "CANCELLED",
265
+ "DELETED",
266
+ "EXPIRED",
267
+ ]);
268
+ const isDocumensoEnvelopeStatus = Schema.is(DocumensoEnvelopeStatusSchema);
148
269
  const mapEnvelopeStatus = (status) => {
149
- switch (status.toUpperCase()) {
150
- case "DRAFT":
151
- return "draft";
152
- case "PENDING":
153
- case "PROCESSING":
154
- case "SENT":
155
- return "sent";
156
- case "SIGNED":
157
- case "COMPLETED":
158
- case "CLOSED":
159
- return "completed";
160
- case "REJECTED":
161
- case "DECLINED":
162
- return "declined";
163
- case "CANCELED":
164
- case "CANCELLED":
165
- return "cancelled";
166
- case "DELETED":
167
- return "deleted";
168
- case "EXPIRED":
169
- return "expired";
170
- default:
171
- return "sent";
172
- }
270
+ const normalized = status.toUpperCase();
271
+ if (!isDocumensoEnvelopeStatus(normalized))
272
+ return "sent";
273
+ return Match.value(normalized).pipe(Match.when("DRAFT", () => "draft"), Match.whenOr("PENDING", "PROCESSING", "SENT", () => "sent"), Match.whenOr("SIGNED", "COMPLETED", "CLOSED", () => "completed"), Match.whenOr("REJECTED", "DECLINED", () => "declined"), Match.whenOr("CANCELED", "CANCELLED", () => "cancelled"), Match.when("DELETED", () => "deleted"), Match.when("EXPIRED", () => "expired"), Match.orElse(() => "sent"));
173
274
  };
174
275
  const envelopeSignedDownloadUrl = (baseUrl, envelopeItemId) => {
175
276
  const encodedItemId = documensoPathId(envelopeItemId);
@@ -183,7 +284,7 @@ const envelopeSignedDownloadUrlFromEnvelope = (baseUrl, envelope) => {
183
284
  ? undefined
184
285
  : envelopeSignedDownloadUrl(baseUrl, envelopeItemId);
185
286
  };
186
- const mapEnvelopeToRemoteRequest = (baseUrl, envelope) => {
287
+ const mapEnvelopeToDocumensoEnvelope = (baseUrl, envelope) => {
187
288
  const signingUrl = envelope.recipients?.[0]?.signingUrl;
188
289
  const downloadUrl = envelopeSignedDownloadUrlFromEnvelope(baseUrl, envelope);
189
290
  return {
@@ -201,8 +302,8 @@ const fetchEnvelopeResult = (http, options, baseUrl, id) => http.requestJson({
201
302
  method: "GET",
202
303
  url: `${baseUrl}/envelope/${documensoPathId(id)}`,
203
304
  headers: { Authorization: documensoAuthorization(options) },
204
- }, DocumensoEnvelopeResultSchema, SignatureKitSchemaNameValue.documensoEnvelopeResult);
205
- const getEnvelope = (http, options, baseUrl, id) => fetchEnvelopeResult(http, options, baseUrl, id).pipe(Effect.map((result) => mapEnvelopeToRemoteRequest(baseUrl, result)));
305
+ }, DocumensoEnvelopeResultSchema, DocumensoSchemaName.envelopeResult);
306
+ const getEnvelope = (http, options, baseUrl, id) => fetchEnvelopeResult(http, options, baseUrl, id).pipe(Effect.map((result) => mapEnvelopeToDocumensoEnvelope(baseUrl, result)));
206
307
  const listEnvelopes = (http, options, baseUrl) => {
207
308
  return Stream.paginate(DOCUMENSO_LIST_FIRST_PAGE, (page) => {
208
309
  const url = new URL(`${baseUrl}/envelope`);
@@ -214,12 +315,12 @@ const listEnvelopes = (http, options, baseUrl) => {
214
315
  method: "GET",
215
316
  url: url.toString(),
216
317
  headers: { Authorization: documensoAuthorization(options) },
217
- }, DocumensoEnvelopeListResultSchema, SignatureKitSchemaNameValue.documensoEnvelopeListResult)
318
+ }, DocumensoEnvelopeListResultSchema, DocumensoSchemaName.envelopeListResult)
218
319
  .pipe(Effect.map((result) => [
219
- result.data.map((envelope) => mapEnvelopeToRemoteRequest(baseUrl, envelope)),
320
+ result.data.map((envelope) => mapEnvelopeToDocumensoEnvelope(baseUrl, envelope)),
220
321
  documensoNextPage(result.pagination, page),
221
322
  ]));
222
- }).pipe(Stream.runCollect, Effect.map((requests) => requests.flat()));
323
+ }).pipe(Stream.runCollect);
223
324
  };
224
325
  const cancelEnvelope = (http, options, baseUrl, envelopeId) => http.requestVoid({
225
326
  provider: PROVIDER,
@@ -243,29 +344,36 @@ const deleteEnvelope = (http, options, baseUrl, envelopeId) => http
243
344
  body: JSON.stringify({ envelopeId }),
244
345
  })
245
346
  .pipe(Effect.catchIf((error) => error.code === SignatureKitErrorCodeValue.http && error.status === 404, () => Effect.void));
246
- const downloadSignedEnvelopeItem = (http, options, baseUrl, envelopeItemId) => {
247
- const encodedItemId = documensoPathId(envelopeItemId);
248
- const url = new URL(`${baseUrl}/envelope/item/${encodedItemId}/download`);
249
- url.searchParams.set("version", "signed");
250
- return requestEnvelopeSignedBytes(http, options, baseUrl, url.toString());
251
- };
252
347
  const downloadSignedEnvelopeDocument = (http, options, baseUrl, envelopeId) => fetchEnvelopeResult(http, options, baseUrl, envelopeId).pipe(Effect.flatMap((envelope) => {
253
- const downloadUrl = envelopeSignedDownloadUrlFromEnvelope(baseUrl, envelope);
254
- if (downloadUrl !== undefined) {
255
- return requestEnvelopeSignedBytes(http, options, baseUrl, downloadUrl);
348
+ if (mapEnvelopeStatus(envelope.status) !== "completed") {
349
+ return Effect.fail(new SignatureKitError({
350
+ code: SignatureKitErrorCodeValue.unsupportedOperation,
351
+ retryable: false,
352
+ provider: PROVIDER,
353
+ operation: DocumensoOperation.download,
354
+ reason: `Documenso envelope ${envelopeId} is not completed yet (status: ${envelope.status ?? "unknown"}); the signed document does not exist.`,
355
+ }));
256
356
  }
257
- if (envelope.envelopeItems?.[0]?.id === undefined) {
357
+ const envelopeItemId = envelope.envelopeItems?.[0]?.id;
358
+ if (envelopeItemId === undefined) {
258
359
  return Effect.fail(new SignatureKitError({
259
- code: SignatureKitErrorCodeValue.responseShape,
360
+ code: SignatureKitErrorCodeValue.unsupportedOperation,
260
361
  retryable: false,
261
362
  provider: PROVIDER,
262
- operation: SignatureKitOperationValue.remoteDownload,
363
+ operation: DocumensoOperation.download,
263
364
  reason: `Documenso envelope ${envelopeId} has no downloadable item ID.`,
264
365
  }));
265
366
  }
266
- return downloadSignedEnvelopeItem(http, options, baseUrl, envelope.envelopeItems[0].id);
367
+ return requestEnvelopeSignedBytes(http, options, baseUrl, envelopeSignedDownloadUrl(baseUrl, envelopeItemId));
267
368
  }));
268
- const createRemoteRequest = (http, options, baseUrl, input) => createEnvelope(http, options, baseUrl, input).pipe(Effect.flatMap((envelope) => {
369
+ const shouldRollbackDocumensoCreate = (error) => error.code === SignatureKitErrorCodeValue.http &&
370
+ error.status !== undefined &&
371
+ error.status >= 400 &&
372
+ error.status < 500 &&
373
+ error.status !== 408 &&
374
+ error.status !== 409 &&
375
+ error.status !== 429;
376
+ const createDocumensoEnvelopeRequest = (http, options, baseUrl, input) => createEnvelope(http, options, baseUrl, input).pipe(Effect.flatMap((envelope) => {
269
377
  if (input.send === false) {
270
378
  return Effect.succeed({
271
379
  provider: PROVIDER,
@@ -275,23 +383,28 @@ const createRemoteRequest = (http, options, baseUrl, input) => createEnvelope(ht
275
383
  detailsUrl: `${baseUrl}/envelope/${documensoPathId(envelope.id)}`,
276
384
  });
277
385
  }
278
- return distributeEnvelope(http, options, baseUrl, input, envelope).pipe(Effect.catch((error) => deleteEnvelope(http, options, baseUrl, envelope.id).pipe(Effect.catch(() => Effect.void), Effect.flatMap(() => Effect.fail(error)))));
386
+ return distributeEnvelope(http, options, baseUrl, input, envelope).pipe(Effect.catch((error) => shouldRollbackDocumensoCreate(error)
387
+ ? deleteEnvelope(http, options, baseUrl, envelope.id).pipe(Effect.catch(() => Effect.void), Effect.flatMap(() => Effect.fail(error)))
388
+ : Effect.fail(error)));
279
389
  }));
280
390
  export const DocumensoSignatureRequestProvider = () => Provider.effect(DocumensoSignatureRequest, Effect.gen(function* () {
281
391
  const options = yield* DocumensoCredentials;
282
392
  const http = yield* SignatureHttpClient;
283
393
  const baseUrl = documensoBaseUrl(options);
284
394
  return DocumensoSignatureRequest.Provider.of({
285
- diff: ({ olds }) => Effect.succeed(olds === undefined ? undefined : { action: "noop" }),
286
- list: () => listEnvelopes(http, options, baseUrl),
395
+ nuke: { skip: true },
396
+ diff: documensoSignatureRequestDiff,
397
+ list: () =>
398
+ // Retained resources must not feed account-wide nuke enumeration.
399
+ Effect.succeed([]),
287
400
  read: ({ output }) => output === undefined
288
401
  ? Effect.succeed(undefined)
289
402
  : getEnvelope(http, options, baseUrl, output.id).pipe(Effect.catchIf((error) => error.code === SignatureKitErrorCodeValue.http && error.status === 404, () => Effect.succeed(undefined))),
290
403
  reconcile: Effect.fn(function* ({ news, output }) {
291
404
  if (output !== undefined)
292
405
  return output;
293
- const input = yield* remoteSignatureInputFromResourceProps(PROVIDER, news);
294
- return yield* createRemoteRequest(http, options, baseUrl, input);
406
+ const input = yield* documensoSignatureRequestInputFromResourceProps(news);
407
+ return yield* createDocumensoEnvelopeRequest(http, options, baseUrl, input);
295
408
  }),
296
409
  delete: ({ output }) => deleteEnvelope(http, options, baseUrl, output.id),
297
410
  });
@@ -305,7 +418,7 @@ export const getDocumensoSignatureRequest = (options, id) => Effect.gen(function
305
418
  retryable: false,
306
419
  provider: PROVIDER,
307
420
  operation: SignatureKitOperationValue.schemaDecode,
308
- schemaName: SignatureKitSchemaNameValue.documensoProviderOptions,
421
+ schemaName: DocumensoSchemaName.providerOptions,
309
422
  issueMessage: String(issue),
310
423
  })));
311
424
  const http = yield* SignatureHttpClient;
@@ -317,7 +430,7 @@ export const listDocumensoSignatureRequests = (options) => Effect.gen(function*
317
430
  retryable: false,
318
431
  provider: PROVIDER,
319
432
  operation: SignatureKitOperationValue.schemaDecode,
320
- schemaName: SignatureKitSchemaNameValue.documensoProviderOptions,
433
+ schemaName: DocumensoSchemaName.providerOptions,
321
434
  issueMessage: String(issue),
322
435
  })));
323
436
  const http = yield* SignatureHttpClient;
@@ -329,7 +442,7 @@ export const cancelDocumensoSignatureRequest = (options, id) => Effect.gen(funct
329
442
  retryable: false,
330
443
  provider: PROVIDER,
331
444
  operation: SignatureKitOperationValue.schemaDecode,
332
- schemaName: SignatureKitSchemaNameValue.documensoProviderOptions,
445
+ schemaName: DocumensoSchemaName.providerOptions,
333
446
  issueMessage: String(issue),
334
447
  })));
335
448
  const http = yield* SignatureHttpClient;
@@ -341,7 +454,7 @@ export const deleteDocumensoSignatureRequest = (options, id) => Effect.gen(funct
341
454
  retryable: false,
342
455
  provider: PROVIDER,
343
456
  operation: SignatureKitOperationValue.schemaDecode,
344
- schemaName: SignatureKitSchemaNameValue.documensoProviderOptions,
457
+ schemaName: DocumensoSchemaName.providerOptions,
345
458
  issueMessage: String(issue),
346
459
  })));
347
460
  const http = yield* SignatureHttpClient;
@@ -353,7 +466,7 @@ export const downloadDocumensoSignedDocument = (options, envelopeId) => Effect.g
353
466
  retryable: false,
354
467
  provider: PROVIDER,
355
468
  operation: SignatureKitOperationValue.schemaDecode,
356
- schemaName: SignatureKitSchemaNameValue.documensoProviderOptions,
469
+ schemaName: DocumensoSchemaName.providerOptions,
357
470
  issueMessage: String(issue),
358
471
  })));
359
472
  const http = yield* SignatureHttpClient;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@signature-kit/documenso",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "license": "MIT",
5
5
  "files": [
6
6
  "dist",
@@ -27,7 +27,8 @@
27
27
  "test": "vitest run"
28
28
  },
29
29
  "dependencies": {
30
- "@signature-kit/core": "^0.2.0",
30
+ "@signature-kit/http": "^0.1.0",
31
+ "@signature-kit/signatures": "^0.1.0",
31
32
  "alchemy": "2.0.0-beta.57",
32
33
  "effect": "4.0.0-beta.86"
33
34
  },