SignatureKit
Provider APIs

Assinafy

Create Assinafy requests with account-scoped credentials and typed SignatureKit errors.

Assinafy creates a document, registers the signer, and creates the assignment in the configured account. SignatureKit keeps the request shape typed and leaves ceremony ownership to Assinafy.

Installation

npm install @signature-kit/http @signature-kit/assinafy

When to use

Use Assinafy when account-level organization and assignment tracking belong in Assinafy. Use local signing when your app owns the signature bytes and placement.

Keep credentials Redacted

Provider tokens enter as Redacted.make(...) and are unwrapped only inside the package HTTP boundary. Never pass remote tokens to React components or logs.

Minimal request

assinafy.ts
import * as Alchemy from "alchemy"
import { AssinafySignatureRequest, providers as assinafyProviders } from "@signature-kit/assinafy"
import { signatureHttpClientLive } from "@signature-kit/http"
import { Effect, Layer, Redacted } from "effect"

export default class Contracts extends Alchemy.Stack<Contracts>()(
  "Contracts",
  {
    providers: Layer.merge(
      assinafyProviders({
        apiKey: Redacted.make(process.env.ASSINAFY_API_KEY ?? ""),
        accountId: process.env.ASSINAFY_ACCOUNT_ID ?? "",
        environment: "sandbox",
      }),
      signatureHttpClientLive,
    ),
    state: Alchemy.inMemoryState(),
  },
  Effect.gen(function* () {
    return yield* AssinafySignatureRequest("service-agreement", {
      title: "Service agreement",
      message: "Review and sign this document.",
      documents: [{ fileName: "contract.pdf", mimeType: "application/pdf", contentBase64: pdfBase64 }],
      recipients: [{ name: "Ada Lovelace", email: "ada@example.com", routingOrder: 1 }],
      send: true,
    })
  }),
) {}

Provider facts

  • Credentials include both API key and account id. Alternatively, pass accessToken instead of apiKey to authenticate with Authorization: Bearer <token> rather than X-Api-Key.
  • The adapter creates document, signer, and assignment in one request flow.
  • Recoverable HTTP and response-shape failures surface as SignatureKitError.

Errors

Invalid input, remote HTTP failures, and invalid response shapes fail as SignatureKitError. The provider, operation, and HTTP status fields are preserved when the upstream response exposes them.

Wait for a final state

waitForAssinafySignatureRequest(options, id, pollInterval) reads immediately and polls while the request is draft or sent. It returns the provider's final state, including cancellation, rejection, deletion, or expiry; inspect state before downloading. The interval must be positive and finite. Read failures propagate immediately without automatic retry. Interruption cancels the active read and stops future polls. The caller owns the deadline:

import { waitForAssinafySignatureRequest } from "@signature-kit/assinafy";
import { signatureHttpClientLive } from "@signature-kit/http";
import { Duration, Effect } from "effect";
import type { AssinafyProviderOptions } from "@signature-kit/assinafy";

declare const options: AssinafyProviderOptions;
declare const requestId: string;

const program = waitForAssinafySignatureRequest(options, requestId, Duration.seconds(2)).pipe(
  Effect.timeout(Duration.minutes(5)),
  Effect.provide(signatureHttpClientLive),
);

How is this guide?

On this page