@signature-kit/docuseal 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,21 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.0
4
+
5
+ - DocuSeal now owns its submission props, attributes, state schema, schema names,
6
+ and retained no-op diff instead of using core remote-signature contracts.
7
+ - Refuse signed-document downloads before a submission is completed, returning a
8
+ typed `unsupportedOperation` instead of silently returning the unsigned source
9
+ document.
10
+ - Advertise `downloadUrl` only for completed submissions, because draft
11
+ submission document URLs can point at unsigned bytes.
12
+ - Add offline local-HTTP-server coverage for DocuSeal provider behavior in the
13
+ default test suite.
14
+
15
+ Breaking: request props now use `DocuSealSubmissionProps` with `contentBase64`
16
+ documents, and `getDocuSealSignatureRequest` / `listDocuSealSignatureRequests`
17
+ return `DocuSealSubmissionAttributes` instead of core `RemoteSignature*` types.
18
+
3
19
  ## 0.2.0
4
20
 
5
21
  - Deduplicate submitter roles so recipients sharing a role are accepted by DocuSeal.
@@ -12,4 +28,4 @@
12
28
 
13
29
  - Initial npm-ready release for `@signature-kit/docuseal`.
14
30
  - Published package metadata, MIT license, README, and package-local changelog.
15
- - Ships alchemy v2 remote-signature provider for DocuSeal submission creation, lookup, deletion, and signed-document download.
31
+ - Ships an Alchemy v2 remote-signature provider for DocuSeal submission creation, lookup, deletion, and signed-document download.
package/README.md CHANGED
@@ -1,24 +1,79 @@
1
1
  # @signature-kit/docuseal
2
2
 
3
- Alchemy v2 remote-signature provider for DocuSeal submission creation, lookup, deletion, and signed-document download.
3
+ Alchemy v2 remote-signature provider for DocuSeal submission creation, lookup, listing, deletion, and completed-document download.
4
4
 
5
5
  ## Install
6
6
 
7
7
  ```sh
8
- bun add @signature-kit/docuseal effect alchemy
8
+ bun add @signature-kit/docuseal @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 DocuSeal credentials and resource providers.
12
12
 
13
- - `@signature-kit/docuseal`
13
+ ## Public surface
14
14
 
15
- ## Runtime model
15
+ - `@signature-kit/docuseal` — DocuSeal submission/document/submitter schemas, `DocuSealSignatureRequest`, `DocuSealProviders`, `providers`, `getDocuSealSignatureRequest`, `listDocuSealSignatureRequests`, `deleteDocuSealSignatureRequest`, and `downloadDocuSealSignedDocument`.
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 submission | Yes |
22
+ | Get submission | Yes |
23
+ | List submissions | Yes |
24
+ | Cancel submission | No public cancel helper is exposed |
25
+ | Delete submission | Yes |
26
+ | Download signed document | Yes, only for completed submissions with provider document URLs |
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. Create is a single submission POST, so there is no multi-step rollback sequence to compensate after a partial provider workflow.
29
+
30
+ ## Example
31
+
32
+ ```ts
33
+ import * as Alchemy from "alchemy";
34
+ import {
35
+ DocuSealSignatureRequest,
36
+ downloadDocuSealSignedDocument,
37
+ providers as docusealProviders,
38
+ type DocuSealProviderOptions,
39
+ } from "@signature-kit/docuseal";
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: DocuSealProviderOptions = {
47
+ apiKey: Redacted.make(apiKey),
48
+ };
49
+
50
+ export default class Contracts extends Alchemy.Stack<Contracts>()(
51
+ "Contracts",
52
+ {
53
+ providers: Layer.merge(docusealProviders(options), signatureHttpClientLive),
54
+ state: Alchemy.inMemoryState(),
55
+ },
56
+ Effect.gen(function* () {
57
+ return yield* DocuSealSignatureRequest("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 = (id: string) =>
69
+ downloadDocuSealSignedDocument(options, id).pipe(Effect.provide(signatureHttpClientLive));
70
+ ```
71
+
72
+ ## Errors and i18n
73
+
74
+ 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`.
75
+
76
+ Docs: <https://signaturekit.dev/en-US/docs/providers/docuseal>.
22
77
 
23
78
  ## License
24
79
 
package/dist/index.d.ts CHANGED
@@ -1,9 +1,80 @@
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 DocuSealProviderId = "docuseal";
7
+ export declare const DocuSealSubmissionStateSchema: Schema.Literals<readonly ["draft", "sent", "completed", "cancelled", "deleted", "declined", "expired"]>;
8
+ export type DocuSealSubmissionState = (typeof DocuSealSubmissionStateSchema)["Type"];
9
+ export declare const DocuSealSubmissionDocumentSchema: Schema.Struct<{
10
+ readonly fileName: Schema.NonEmptyString;
11
+ readonly mimeType: Schema.NonEmptyString;
12
+ readonly content: Schema.Uint8Array;
13
+ }>;
14
+ export type DocuSealSubmissionDocument = (typeof DocuSealSubmissionDocumentSchema)["Type"];
15
+ export declare const DocuSealSubmissionDocumentPropsSchema: Schema.Struct<{
16
+ readonly fileName: Schema.NonEmptyString;
17
+ readonly mimeType: Schema.NonEmptyString;
18
+ readonly contentBase64: Schema.ConstraintDecoder<string, never>;
19
+ }>;
20
+ export type DocuSealSubmissionDocumentProps = (typeof DocuSealSubmissionDocumentPropsSchema)["Type"];
21
+ export declare const DocuSealSubmitterSchema: Schema.Struct<{
22
+ readonly name: Schema.NonEmptyString;
23
+ readonly email: Schema.NonEmptyString;
24
+ readonly role: Schema.optional<Schema.NonEmptyString>;
25
+ readonly routingOrder: Schema.optional<Schema.Number>;
26
+ }>;
27
+ export type DocuSealSubmitter = (typeof DocuSealSubmitterSchema)["Type"];
28
+ export declare const DocuSealSubmissionInputSchema: Schema.Struct<{
29
+ readonly title: Schema.NonEmptyString;
30
+ readonly subject: Schema.optional<Schema.NonEmptyString>;
31
+ readonly message: Schema.optional<Schema.NonEmptyString>;
32
+ readonly documents: Schema.NonEmptyArray<Schema.Struct<{
33
+ readonly fileName: Schema.NonEmptyString;
34
+ readonly mimeType: Schema.NonEmptyString;
35
+ readonly content: Schema.Uint8Array;
36
+ }>>;
37
+ readonly recipients: Schema.NonEmptyArray<Schema.Struct<{
38
+ readonly name: Schema.NonEmptyString;
39
+ readonly email: Schema.NonEmptyString;
40
+ readonly role: Schema.optional<Schema.NonEmptyString>;
41
+ readonly routingOrder: Schema.optional<Schema.Number>;
42
+ }>>;
43
+ readonly send: Schema.optional<Schema.Boolean>;
44
+ readonly expiresAt: Schema.optional<Schema.Date>;
45
+ readonly redirectUrl: Schema.optional<Schema.NonEmptyString>;
46
+ }>;
47
+ export type DocuSealSubmissionInput = (typeof DocuSealSubmissionInputSchema)["Type"];
48
+ export declare const DocuSealSubmissionPropsSchema: Schema.Struct<{
49
+ readonly title: Schema.NonEmptyString;
50
+ readonly subject: Schema.optional<Schema.NonEmptyString>;
51
+ readonly message: Schema.optional<Schema.NonEmptyString>;
52
+ readonly documents: Schema.NonEmptyArray<Schema.Struct<{
53
+ readonly fileName: Schema.NonEmptyString;
54
+ readonly mimeType: Schema.NonEmptyString;
55
+ readonly contentBase64: Schema.ConstraintDecoder<string, never>;
56
+ }>>;
57
+ readonly recipients: Schema.NonEmptyArray<Schema.Struct<{
58
+ readonly name: Schema.NonEmptyString;
59
+ readonly email: Schema.NonEmptyString;
60
+ readonly role: Schema.optional<Schema.NonEmptyString>;
61
+ readonly routingOrder: Schema.optional<Schema.Number>;
62
+ }>>;
63
+ readonly send: Schema.optional<Schema.Boolean>;
64
+ readonly expiresAt: Schema.optional<Schema.Date>;
65
+ readonly redirectUrl: Schema.optional<Schema.NonEmptyString>;
66
+ }>;
67
+ export type DocuSealSubmissionProps = (typeof DocuSealSubmissionPropsSchema)["Type"];
68
+ export declare const DocuSealSubmissionAttributesSchema: Schema.Struct<{
69
+ readonly provider: Schema.Literal<"docuseal">;
70
+ readonly id: Schema.NonEmptyString;
71
+ readonly state: Schema.Literals<readonly ["draft", "sent", "completed", "cancelled", "deleted", "declined", "expired"]>;
72
+ readonly providerStatus: Schema.optional<Schema.String>;
73
+ readonly signingUrl: Schema.optional<Schema.String>;
74
+ readonly detailsUrl: Schema.optional<Schema.String>;
75
+ readonly downloadUrl: Schema.optional<Schema.String>;
76
+ }>;
77
+ export type DocuSealSubmissionAttributes = (typeof DocuSealSubmissionAttributesSchema)["Type"];
7
78
  declare const DocuSealSubmittersOrderSchema: Schema.Literals<readonly ["preserved", "random"]>;
8
79
  export type DocuSealSubmittersOrder = (typeof DocuSealSubmittersOrderSchema)["Type"];
9
80
  export declare const DocuSealProviderOptionsSchema: Schema.Struct<{
@@ -13,7 +84,7 @@ export declare const DocuSealProviderOptionsSchema: Schema.Struct<{
13
84
  readonly submittersOrder: Schema.optional<Schema.Literals<readonly ["preserved", "random"]>>;
14
85
  }>;
15
86
  export type DocuSealProviderOptions = (typeof DocuSealProviderOptionsSchema)["Type"];
16
- export type DocuSealSignatureRequest = Resource<"SignatureKit.DocuSealSignatureRequest", RemoteSignatureRequestProps, RemoteSignatureRequest>;
87
+ export type DocuSealSignatureRequest = Resource<"SignatureKit.DocuSealSignatureRequest", DocuSealSubmissionProps, DocuSealSubmissionAttributes>;
17
88
  export declare const DocuSealSignatureRequest: import("alchemy").ResourceClass<DocuSealSignatureRequest>;
18
89
  declare const DocuSealCredentials_base: Context.ServiceClass<DocuSealCredentials, "@signature-kit/docuseal/Credentials", {
19
90
  readonly apiKey: Redacted.Redacted<string>;
@@ -29,8 +100,8 @@ declare const DocuSealProviders_base: Provider.ProviderCollection<DocuSealProvid
29
100
  export declare class DocuSealProviders extends DocuSealProviders_base {
30
101
  }
31
102
  export declare const providers: (options: DocuSealProviderOptions) => Layer.Layer<DocuSealProviders, SignatureKitError, SignatureHttpClient>;
32
- export declare const getDocuSealSignatureRequest: (options: DocuSealProviderOptions, id: string) => Effect.Effect<RemoteSignatureRequest, SignatureKitError, SignatureHttpClient>;
33
- export declare const listDocuSealSignatureRequests: (options: DocuSealProviderOptions) => Effect.Effect<readonly RemoteSignatureRequest[], SignatureKitError, SignatureHttpClient>;
103
+ export declare const getDocuSealSignatureRequest: (options: DocuSealProviderOptions, id: string) => Effect.Effect<DocuSealSubmissionAttributes, SignatureKitError, SignatureHttpClient>;
104
+ export declare const listDocuSealSignatureRequests: (options: DocuSealProviderOptions) => Effect.Effect<readonly DocuSealSubmissionAttributes[], SignatureKitError, SignatureHttpClient>;
34
105
  export declare const deleteDocuSealSignatureRequest: (options: DocuSealProviderOptions, id: string) => Effect.Effect<void, SignatureKitError, SignatureHttpClient>;
35
106
  export declare const downloadDocuSealSignedDocument: (options: DocuSealProviderOptions, id: string) => Effect.Effect<Uint8Array, SignatureKitError, SignatureHttpClient>;
36
107
  export {};
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,EAMlB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAGV,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;AAMlF,QAAA,MAAM,6BAA6B,mDAA2C,CAAC;AAC/E,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAErF,eAAO,MAAM,6BAA6B;;;;;EAKxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AA8DrF,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAC7C,uCAAuC,EACvC,2BAA2B,EAC3B,sBAAsB,CACvB,CAAC;AAEF,eAAO,MAAM,wBAAwB,2DAGpC,CAAC;;;;;;;AAEF,qBAAa,mBAAoB,SAAQ,wBAGC;CAAG;AAE7C,eAAO,MAAM,wBAAwB,GACnC,SAAS,uBAAuB,KAC/B,KAAK,CAAC,KAAK,CAAC,mBAAmB,EAAE,iBAAiB,CAgBlD,CAAC;AA0SJ,eAAO,MAAM,gCAAgC,kHA6B1C,CAAC;;AACJ,qBAAa,iBAAkB,SAAQ,sBAEtC;CAAG;AAEJ,eAAO,MAAM,SAAS,GAAI,SAAS,uBAAuB,2EAIvD,CAAC;AAEJ,eAAO,MAAM,2BAA2B,GACtC,SAAS,uBAAuB,EAChC,IAAI,MAAM,KACT,MAAM,CAAC,MAAM,CAAC,sBAAsB,EAAE,iBAAiB,EAAE,mBAAmB,CAoB3E,CAAC;AAEL,eAAO,MAAM,6BAA6B,GACxC,SAAS,uBAAuB,KAC/B,MAAM,CAAC,MAAM,CAAC,SAAS,sBAAsB,EAAE,EAAE,iBAAiB,EAAE,mBAAmB,CAiBtF,CAAC;AAEL,eAAO,MAAM,8BAA8B,GACzC,SAAS,uBAAuB,EAChC,IAAI,MAAM,KACT,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,mBAAmB,CAiBzD,CAAC;AAEL,eAAO,MAAM,8BAA8B,GACzC,SAAS,uBAAuB,EAChC,IAAI,MAAM,KACT,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":"AACA,OAAO,EACL,iBAAiB,EAIlB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAqB,MAAM,qBAAqB,CAAC;AAE7E,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAiB,QAAQ,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAC;AAiBzF,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAG7C,eAAO,MAAM,6BAA6B,yGAQxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAErF,eAAO,MAAM,gCAAgC;;;;EAI3C,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,gCAAgC,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3F,eAAO,MAAM,qCAAqC;;;;EAIhD,CAAC;AACH,MAAM,MAAM,+BAA+B,GACzC,CAAC,OAAO,qCAAqC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAO,MAAM,uBAAuB;;;;;EAKlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;EASxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAErF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;EASxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAErF,eAAO,MAAM,kCAAkC;;;;;;;;EAQ7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,OAAO,kCAAkC,CAAC,CAAC,MAAM,CAAC,CAAC;AA2D/F,QAAA,MAAM,6BAA6B,mDAA2C,CAAC;AAC/E,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAErF,eAAO,MAAM,6BAA6B;;;;;EAKxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AA6DrF,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAC7C,uCAAuC,EACvC,uBAAuB,EACvB,4BAA4B,CAC7B,CAAC;AAEF,eAAO,MAAM,wBAAwB,2DAGpC,CAAC;;;;;;;AAEF,qBAAa,mBAAoB,SAAQ,wBAGC;CAAG;AAE7C,eAAO,MAAM,wBAAwB,GACnC,SAAS,uBAAuB,KAC/B,KAAK,CAAC,KAAK,CAAC,mBAAmB,EAAE,iBAAiB,CAgBlD,CAAC;AAsTJ,eAAO,MAAM,gCAAgC,kHAgC1C,CAAC;;AACJ,qBAAa,iBAAkB,SAAQ,sBAEtC;CAAG;AAEJ,eAAO,MAAM,SAAS,GAAI,SAAS,uBAAuB,2EAIvD,CAAC;AAEJ,eAAO,MAAM,2BAA2B,GACtC,SAAS,uBAAuB,EAChC,IAAI,MAAM,KACT,MAAM,CAAC,MAAM,CAAC,4BAA4B,EAAE,iBAAiB,EAAE,mBAAmB,CAoBjF,CAAC;AAEL,eAAO,MAAM,6BAA6B,GACxC,SAAS,uBAAuB,KAC/B,MAAM,CAAC,MAAM,CAAC,SAAS,4BAA4B,EAAE,EAAE,iBAAiB,EAAE,mBAAmB,CAiB5F,CAAC;AAEL,eAAO,MAAM,8BAA8B,GACzC,SAAS,uBAAuB,EAChC,IAAI,MAAM,KACT,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,mBAAmB,CAiBzD,CAAC;AAEL,eAAO,MAAM,8BAA8B,GACzC,SAAS,uBAAuB,EAChC,IAAI,MAAM,KACT,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,iBAAiB,EAAE,mBAAmB,CAiB/D,CAAC"}
package/dist/index.js CHANGED
@@ -1,10 +1,111 @@
1
1
  import { bytesToBase64 } from "@signature-kit/crypto/base64";
2
- import { SignatureKitError, SignatureKitErrorCodeValue, SignatureKitOperationValue, SignatureKitSchemaNameValue, redactedStringSchema, remoteSignatureInputFromResourceProps, } from "@signature-kit/core/config";
3
- import { SignatureHttpClient, normalizedBaseUrl } from "@signature-kit/core/http";
2
+ import { SignatureKitError, SignatureKitErrorCodeValue, SignatureKitOperationValue, redactedStringSchema, } from "@signature-kit/signatures";
3
+ import { SignatureHttpClient, normalizedBaseUrl } from "@signature-kit/http";
4
4
  import { Resource } from "alchemy";
5
5
  import * as Provider from "alchemy/Provider";
6
- import { Context, Effect, Layer, Option, Redacted, Schema, Stream } from "effect";
7
- const PROVIDER = "docuseal";
6
+ import { Context, Effect, Layer, Match, Option, Redacted, Schema, Stream } from "effect";
7
+ const DocuSealSchemaName = {
8
+ providerOptions: "DocuSealProviderOptions",
9
+ signatureRequestProps: "DocuSealSubmissionProps",
10
+ submissionResult: "DocuSealSubmissionResult",
11
+ submissionsResult: "DocuSealSubmissionsResult",
12
+ submissionDocumentsResult: "DocuSealSubmissionDocumentsResult",
13
+ };
14
+ const DocuSealOperation = {
15
+ create: "docuseal.create",
16
+ download: "docuseal.download",
17
+ };
18
+ const base64String = Schema.String.check(Schema.isBase64());
19
+ export const DocuSealProviderId = "docuseal";
20
+ const PROVIDER = DocuSealProviderId;
21
+ export const DocuSealSubmissionStateSchema = Schema.Literals([
22
+ "draft",
23
+ "sent",
24
+ "completed",
25
+ "cancelled",
26
+ "deleted",
27
+ "declined",
28
+ "expired",
29
+ ]);
30
+ export const DocuSealSubmissionDocumentSchema = Schema.Struct({
31
+ fileName: Schema.NonEmptyString,
32
+ mimeType: Schema.NonEmptyString,
33
+ content: Schema.Uint8Array,
34
+ });
35
+ export const DocuSealSubmissionDocumentPropsSchema = Schema.Struct({
36
+ fileName: Schema.NonEmptyString,
37
+ mimeType: Schema.NonEmptyString,
38
+ contentBase64: base64String,
39
+ });
40
+ export const DocuSealSubmitterSchema = Schema.Struct({
41
+ name: Schema.NonEmptyString,
42
+ email: Schema.NonEmptyString,
43
+ role: Schema.optional(Schema.NonEmptyString),
44
+ routingOrder: Schema.optional(Schema.Number),
45
+ });
46
+ export const DocuSealSubmissionInputSchema = Schema.Struct({
47
+ title: Schema.NonEmptyString,
48
+ subject: Schema.optional(Schema.NonEmptyString),
49
+ message: Schema.optional(Schema.NonEmptyString),
50
+ documents: Schema.NonEmptyArray(DocuSealSubmissionDocumentSchema),
51
+ recipients: Schema.NonEmptyArray(DocuSealSubmitterSchema),
52
+ send: Schema.optional(Schema.Boolean),
53
+ expiresAt: Schema.optional(Schema.Date),
54
+ redirectUrl: Schema.optional(Schema.NonEmptyString),
55
+ });
56
+ export const DocuSealSubmissionPropsSchema = Schema.Struct({
57
+ title: Schema.NonEmptyString,
58
+ subject: Schema.optional(Schema.NonEmptyString),
59
+ message: Schema.optional(Schema.NonEmptyString),
60
+ documents: Schema.NonEmptyArray(DocuSealSubmissionDocumentPropsSchema),
61
+ recipients: Schema.NonEmptyArray(DocuSealSubmitterSchema),
62
+ send: Schema.optional(Schema.Boolean),
63
+ expiresAt: Schema.optional(Schema.Date),
64
+ redirectUrl: Schema.optional(Schema.NonEmptyString),
65
+ });
66
+ export const DocuSealSubmissionAttributesSchema = Schema.Struct({
67
+ provider: Schema.Literal(PROVIDER),
68
+ id: Schema.NonEmptyString,
69
+ state: DocuSealSubmissionStateSchema,
70
+ providerStatus: Schema.optional(Schema.String),
71
+ signingUrl: Schema.optional(Schema.String),
72
+ detailsUrl: Schema.optional(Schema.String),
73
+ downloadUrl: Schema.optional(Schema.String),
74
+ });
75
+ const docusealSignatureRequestNoopDiff = { action: "noop" };
76
+ const docusealSignatureRequestDiff = ({ olds, }) => Effect.succeed(olds === undefined ? undefined : docusealSignatureRequestNoopDiff);
77
+ const docusealSignatureRequestInputFromProps = (props) => {
78
+ const [firstDocument, ...restDocuments] = props.documents;
79
+ return {
80
+ title: props.title,
81
+ documents: [
82
+ {
83
+ fileName: firstDocument.fileName,
84
+ mimeType: firstDocument.mimeType,
85
+ content: Uint8Array.fromBase64(firstDocument.contentBase64),
86
+ },
87
+ ...restDocuments.map((document) => ({
88
+ fileName: document.fileName,
89
+ mimeType: document.mimeType,
90
+ content: Uint8Array.fromBase64(document.contentBase64),
91
+ })),
92
+ ],
93
+ recipients: props.recipients,
94
+ ...(props.subject === undefined ? {} : { subject: props.subject }),
95
+ ...(props.message === undefined ? {} : { message: props.message }),
96
+ ...(props.send === undefined ? {} : { send: props.send }),
97
+ ...(props.expiresAt === undefined ? {} : { expiresAt: props.expiresAt }),
98
+ ...(props.redirectUrl === undefined ? {} : { redirectUrl: props.redirectUrl }),
99
+ };
100
+ };
101
+ const docusealSignatureRequestInputFromResourceProps = (props) => Schema.decodeUnknownEffect(DocuSealSubmissionPropsSchema)(props).pipe(Effect.mapError((issue) => new SignatureKitError({
102
+ code: SignatureKitErrorCodeValue.invalidInput,
103
+ retryable: false,
104
+ provider: PROVIDER,
105
+ operation: SignatureKitOperationValue.schemaDecode,
106
+ schemaName: DocuSealSchemaName.signatureRequestProps,
107
+ issueMessage: String(issue),
108
+ })), Effect.map(docusealSignatureRequestInputFromProps));
8
109
  const DOCUSEAL_PROVIDER_COLLECTION_ID = "@signature-kit/docuseal/Providers";
9
110
  const DEFAULT_BASE_URL = "https://api.docuseal.com";
10
111
  const DocuSealSubmittersOrderSchema = Schema.Literals(["preserved", "random"]);
@@ -70,7 +171,7 @@ export const docuSealCredentialsLayer = (options) => Layer.effect(DocuSealCreden
70
171
  retryable: false,
71
172
  provider: PROVIDER,
72
173
  operation: SignatureKitOperationValue.schemaDecode,
73
- schemaName: SignatureKitSchemaNameValue.docuSealProviderOptions,
174
+ schemaName: DocuSealSchemaName.providerOptions,
74
175
  issueMessage: String(issue),
75
176
  }))));
76
177
  const docuSealBaseUrl = (options) => options.baseUrl === undefined ? DEFAULT_BASE_URL : normalizedBaseUrl(options.baseUrl);
@@ -78,8 +179,7 @@ const authHeaders = (options) => ({
78
179
  "X-Auth-Token": Redacted.value(options.apiKey),
79
180
  });
80
181
  const normalizeSubmissionId = (submissionId) => typeof submissionId === "string" ? submissionId : submissionId.toString();
81
- const normalizeSubmissionPathId = (submissionId) => encodeURIComponent(submissionId);
82
- const docuSealSubmissionUrl = (baseUrl, submissionId) => `${baseUrl}/submissions/${normalizeSubmissionPathId(submissionId)}`;
182
+ const docuSealSubmissionUrl = (baseUrl, submissionId) => `${baseUrl}/submissions/${encodeURIComponent(submissionId)}`;
83
183
  const docuSealSubmissionListUrl = (baseUrl, after) => {
84
184
  const url = new URL(`${baseUrl}/submissions`);
85
185
  url.searchParams.set("limit", "100");
@@ -90,27 +190,24 @@ const docuSealSubmissionListUrl = (baseUrl, after) => {
90
190
  const docuSealSubmissionsNextUrl = (baseUrl, pagination) => pagination.next === null
91
191
  ? Option.none()
92
192
  : Option.some(docuSealSubmissionListUrl(baseUrl, pagination.next));
93
- const mapRemoteState = (status) => {
193
+ const DocuSealStatusSchema = Schema.Literals([
194
+ "draft",
195
+ "completed",
196
+ "declined",
197
+ "expired",
198
+ "deleted",
199
+ "archived",
200
+ "cancelled",
201
+ "canceled",
202
+ ]);
203
+ const isDocuSealStatus = Schema.is(DocuSealStatusSchema);
204
+ const docuSealSubmissionState = (status) => {
94
205
  if (status === undefined)
95
206
  return "sent";
96
- switch (status.toLowerCase()) {
97
- case "draft":
98
- return "draft";
99
- case "completed":
100
- return "completed";
101
- case "declined":
102
- return "declined";
103
- case "expired":
104
- return "expired";
105
- case "deleted":
106
- case "archived":
107
- return "deleted";
108
- case "cancelled":
109
- case "canceled":
110
- return "cancelled";
111
- default:
112
- return "sent";
113
- }
207
+ const normalized = status.toLowerCase();
208
+ if (!isDocuSealStatus(normalized))
209
+ return "sent";
210
+ return Match.value(normalized).pipe(Match.when("draft", () => "draft"), Match.when("completed", () => "completed"), Match.when("declined", () => "declined"), Match.when("expired", () => "expired"), Match.whenOr("deleted", "archived", () => "deleted"), Match.whenOr("cancelled", "canceled", () => "cancelled"), Match.orElse(() => "sent"));
114
211
  };
115
212
  const resolveSubmitterRoles = (recipients) => {
116
213
  const roleCounts = new Map();
@@ -128,14 +225,17 @@ const pickSigningUrl = (submission) => submission.submitters?.[0]?.embed_src ??
128
225
  const pickDownloadUrl = (submission) => submission.combined_document_url ??
129
226
  submission.documents?.[0]?.url ??
130
227
  submission.documents?.[0]?.download_url;
131
- const toRemoteSignatureRequest = (baseUrl, submission) => {
228
+ const toDocuSealSubmissionAttributes = (baseUrl, submission) => {
132
229
  const id = normalizeSubmissionId(submission.id);
133
230
  const signingUrl = pickSigningUrl(submission);
134
- const downloadUrl = pickDownloadUrl(submission);
231
+ const state = docuSealSubmissionState(submission.status);
232
+ // Before completion, documents[0].url points at the UNSIGNED source file —
233
+ // advertising it as downloadUrl would hand callers unsigned bytes.
234
+ const downloadUrl = state === "completed" ? pickDownloadUrl(submission) : undefined;
135
235
  return {
136
236
  provider: PROVIDER,
137
237
  id,
138
- state: mapRemoteState(submission.status),
238
+ state,
139
239
  detailsUrl: docuSealSubmissionUrl(baseUrl, id),
140
240
  ...(submission.status === undefined ? {} : { providerStatus: submission.status }),
141
241
  ...(signingUrl === undefined || signingUrl === null ? {} : { signingUrl }),
@@ -167,6 +267,7 @@ const createSubmission = (http, options, baseUrl, input) => {
167
267
  file: bytesToBase64(document.content),
168
268
  position: index,
169
269
  })),
270
+ // DocuSeal accepts completed_redirect_url as both a submission default and a submitter override.
170
271
  submitters: input.recipients.map((recipient, index) => ({
171
272
  name: recipient.name,
172
273
  email: recipient.email,
@@ -182,10 +283,10 @@ const createSubmission = (http, options, baseUrl, input) => {
182
283
  ...(input.subject === undefined ? {} : { subject: input.subject }),
183
284
  ...(input.message === undefined ? {} : { message: { body: input.message } }),
184
285
  }),
185
- }, DocuSealCreateSubmissionResultSchema, SignatureKitSchemaNameValue.docuSealSubmissionResult)
286
+ }, DocuSealCreateSubmissionResultSchema, DocuSealSchemaName.submissionResult)
186
287
  .pipe(Effect.map((result) => {
187
288
  if ("id" in result) {
188
- const mapped = toRemoteSignatureRequest(baseUrl, result);
289
+ const mapped = toDocuSealSubmissionAttributes(baseUrl, result);
189
290
  const providerStatus = result.status ?? result.submitters?.[0]?.status;
190
291
  return {
191
292
  ...mapped,
@@ -206,24 +307,23 @@ const createSubmission = (http, options, baseUrl, input) => {
206
307
  };
207
308
  }));
208
309
  };
209
- const submissionsFromListResult = (result) => result.data;
210
310
  const listSubmissions = (http, options, baseUrl) => Stream.paginate(docuSealSubmissionListUrl(baseUrl), (url) => http
211
311
  .requestJson({
212
312
  provider: PROVIDER,
213
313
  method: "GET",
214
314
  url,
215
315
  headers: authHeaders(options),
216
- }, DocuSealSubmissionsResultSchema, SignatureKitSchemaNameValue.docuSealSubmissionsResult)
316
+ }, DocuSealSubmissionsResultSchema, DocuSealSchemaName.submissionsResult)
217
317
  .pipe(Effect.map((result) => [
218
- submissionsFromListResult(result).map((submission) => toRemoteSignatureRequest(baseUrl, submission)),
318
+ result.data.map((submission) => toDocuSealSubmissionAttributes(baseUrl, submission)),
219
319
  docuSealSubmissionsNextUrl(baseUrl, result.pagination),
220
- ]))).pipe(Stream.runCollect, Effect.map((requests) => requests.flat()));
320
+ ]))).pipe(Stream.runCollect);
221
321
  const fetchSubmission = (http, options, baseUrl, id) => http.requestJson({
222
322
  provider: PROVIDER,
223
323
  method: "GET",
224
324
  url: docuSealSubmissionUrl(baseUrl, id),
225
325
  headers: authHeaders(options),
226
- }, DocuSealSubmissionResultSchema, SignatureKitSchemaNameValue.docuSealSubmissionResult);
326
+ }, DocuSealSubmissionResultSchema, DocuSealSchemaName.submissionResult);
227
327
  const deleteSubmission = (http, options, baseUrl, id) => http
228
328
  .requestVoid({
229
329
  provider: PROVIDER,
@@ -237,8 +337,17 @@ const fetchSubmissionDocuments = (http, options, baseUrl, id) => http.requestJso
237
337
  method: "GET",
238
338
  url: `${docuSealSubmissionUrl(baseUrl, id)}/documents?merge=true`,
239
339
  headers: authHeaders(options),
240
- }, DocuSealSubmissionDocumentsResultSchema, SignatureKitSchemaNameValue.docuSealSubmissionDocumentsResult);
340
+ }, DocuSealSubmissionDocumentsResultSchema, DocuSealSchemaName.submissionDocumentsResult);
241
341
  const downloadDocumentFromSubmission = (http, options, baseUrl, id) => fetchSubmission(http, options, baseUrl, id).pipe(Effect.flatMap((submission) => {
342
+ if (docuSealSubmissionState(submission.status) !== "completed") {
343
+ return Effect.fail(new SignatureKitError({
344
+ code: SignatureKitErrorCodeValue.unsupportedOperation,
345
+ retryable: false,
346
+ provider: PROVIDER,
347
+ operation: DocuSealOperation.download,
348
+ reason: `DocuSeal submission ${id} is not completed yet (status: ${submission.status ?? "unknown"}); the signed document does not exist.`,
349
+ }));
350
+ }
242
351
  const downloadUrl = pickDownloadUrl(submission);
243
352
  if (downloadUrl !== undefined && downloadUrl !== null)
244
353
  return requestBytesFromUrl(http, downloadUrl);
@@ -249,7 +358,7 @@ const downloadDocumentFromSubmission = (http, options, baseUrl, id) => fetchSubm
249
358
  code: SignatureKitErrorCodeValue.responseShape,
250
359
  retryable: false,
251
360
  provider: PROVIDER,
252
- operation: SignatureKitOperationValue.remoteDownload,
361
+ operation: DocuSealOperation.download,
253
362
  reason: `DocuSeal submission ${id} has no downloadable document URL.`,
254
363
  }));
255
364
  }
@@ -261,15 +370,18 @@ export const DocuSealSignatureRequestProvider = () => Provider.effect(DocuSealSi
261
370
  const http = yield* SignatureHttpClient;
262
371
  const baseUrl = docuSealBaseUrl(options);
263
372
  return DocuSealSignatureRequest.Provider.of({
264
- diff: ({ olds }) => Effect.succeed(olds === undefined ? undefined : { action: "noop" }),
265
- list: () => listSubmissions(http, options, baseUrl),
373
+ nuke: { skip: true },
374
+ diff: docusealSignatureRequestDiff,
375
+ list: () =>
376
+ // Retained resources must not feed account-wide nuke enumeration.
377
+ Effect.succeed([]),
266
378
  read: ({ output }) => output === undefined
267
379
  ? Effect.succeed(undefined)
268
- : fetchSubmission(http, options, baseUrl, output.id).pipe(Effect.map((result) => toRemoteSignatureRequest(baseUrl, result)), Effect.catchIf((error) => error.code === SignatureKitErrorCodeValue.http && error.status === 404, () => Effect.succeed(undefined))),
380
+ : fetchSubmission(http, options, baseUrl, output.id).pipe(Effect.map((result) => toDocuSealSubmissionAttributes(baseUrl, result)), Effect.catchIf((error) => error.code === SignatureKitErrorCodeValue.http && error.status === 404, () => Effect.succeed(undefined))),
269
381
  reconcile: Effect.fn(function* ({ news, output }) {
270
382
  if (output !== undefined)
271
383
  return output;
272
- const input = yield* remoteSignatureInputFromResourceProps(PROVIDER, news);
384
+ const input = yield* docusealSignatureRequestInputFromResourceProps(news);
273
385
  return yield* createSubmission(http, options, baseUrl, input);
274
386
  }),
275
387
  delete: ({ output }) => deleteSubmission(http, options, baseUrl, output.id),
@@ -284,12 +396,12 @@ export const getDocuSealSignatureRequest = (options, id) => Effect.gen(function*
284
396
  retryable: false,
285
397
  provider: PROVIDER,
286
398
  operation: SignatureKitOperationValue.schemaDecode,
287
- schemaName: SignatureKitSchemaNameValue.docuSealProviderOptions,
399
+ schemaName: DocuSealSchemaName.providerOptions,
288
400
  issueMessage: String(issue),
289
401
  })));
290
402
  const http = yield* SignatureHttpClient;
291
403
  const baseUrl = docuSealBaseUrl(valid);
292
- return yield* fetchSubmission(http, valid, baseUrl, id).pipe(Effect.map((result) => toRemoteSignatureRequest(baseUrl, result)));
404
+ return yield* fetchSubmission(http, valid, baseUrl, id).pipe(Effect.map((result) => toDocuSealSubmissionAttributes(baseUrl, result)));
293
405
  });
294
406
  export const listDocuSealSignatureRequests = (options) => Effect.gen(function* () {
295
407
  const valid = yield* Schema.decodeUnknownEffect(DocuSealProviderOptionsSchema)(options).pipe(Effect.mapError((issue) => new SignatureKitError({
@@ -297,7 +409,7 @@ export const listDocuSealSignatureRequests = (options) => Effect.gen(function* (
297
409
  retryable: false,
298
410
  provider: PROVIDER,
299
411
  operation: SignatureKitOperationValue.schemaDecode,
300
- schemaName: SignatureKitSchemaNameValue.docuSealProviderOptions,
412
+ schemaName: DocuSealSchemaName.providerOptions,
301
413
  issueMessage: String(issue),
302
414
  })));
303
415
  const http = yield* SignatureHttpClient;
@@ -309,7 +421,7 @@ export const deleteDocuSealSignatureRequest = (options, id) => Effect.gen(functi
309
421
  retryable: false,
310
422
  provider: PROVIDER,
311
423
  operation: SignatureKitOperationValue.schemaDecode,
312
- schemaName: SignatureKitSchemaNameValue.docuSealProviderOptions,
424
+ schemaName: DocuSealSchemaName.providerOptions,
313
425
  issueMessage: String(issue),
314
426
  })));
315
427
  const http = yield* SignatureHttpClient;
@@ -321,7 +433,7 @@ export const downloadDocuSealSignedDocument = (options, id) => Effect.gen(functi
321
433
  retryable: false,
322
434
  provider: PROVIDER,
323
435
  operation: SignatureKitOperationValue.schemaDecode,
324
- schemaName: SignatureKitSchemaNameValue.docuSealProviderOptions,
436
+ schemaName: DocuSealSchemaName.providerOptions,
325
437
  issueMessage: String(issue),
326
438
  })));
327
439
  const http = yield* SignatureHttpClient;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@signature-kit/docuseal",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "license": "MIT",
5
5
  "files": [
6
6
  "dist",
@@ -27,8 +27,9 @@
27
27
  "test": "vitest run"
28
28
  },
29
29
  "dependencies": {
30
- "@signature-kit/core": "^0.2.0",
31
- "@signature-kit/crypto": "^0.2.0",
30
+ "@signature-kit/crypto": "^0.2.1",
31
+ "@signature-kit/http": "^0.1.0",
32
+ "@signature-kit/signatures": "^0.1.0",
32
33
  "alchemy": "2.0.0-beta.57",
33
34
  "effect": "4.0.0-beta.86"
34
35
  },