signyu 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,275 @@
+/**
+ * Types mirroring the SignYu REST API (src/app/api/v1/** in the SignYu repo).
+ * Timestamps are ISO 8601 strings as returned in JSON.
+ */
+/** Document lifecycle state. `PENDING` until sent, `SENT` while out for signature, `COMPLETED` when every signer has signed. */
+type DocumentStatus = "PENDING" | "SENT" | "COMPLETED" | "FAILED" | "CANCELLED" | (string & {});
+/** One stamp rectangle in PDF points, origin at the bottom-left of the page. */
+interface SignaturePosition {
+    /** 1-based page index. */
+    page: number;
+    /** Left edge in PDF points. */
+    x: number;
+    /** Bottom edge in PDF points (origin is bottom-left). */
+    y: number;
+    /** Box width in PDF points (minimum 140). */
+    width: number;
+    /** Box height in PDF points (minimum 110). */
+    height: number;
+}
+interface SignaturePlacement {
+    /** One rectangle per page, 1 to 20 entries, pages must be distinct. */
+    positions: SignaturePosition[];
+}
+interface SignerAdvanced {
+    signaturePlacement?: SignaturePlacement;
+}
+interface SignerInput {
+    /** Signer's full name. */
+    name: string;
+    /** Digits only, at least 10 characters. */
+    phone: string;
+    /** Valid email address. The signing link is emailed here. */
+    email: string;
+    /** Optional custom stamp placement. Omit to use the default fixed slot. */
+    advanced?: SignerAdvanced;
+}
+/** Response of `POST /api/v1/documents`. */
+interface CreatedDocument {
+    documentId: string;
+    name: string;
+    status: DocumentStatus;
+}
+interface SignerCounts {
+    total: number;
+    signed: number;
+}
+interface DocumentSummary {
+    documentId: string;
+    name: string;
+    status: DocumentStatus;
+    createdAt: string;
+    signers: SignerCounts;
+}
+/** Response of `GET /api/v1/documents`. */
+interface DocumentList {
+    documents: DocumentSummary[];
+    limit: number;
+    offset: number;
+}
+interface DocumentSigner {
+    signerId: string;
+    name: string;
+    email: string | null;
+    phone: string;
+    signingOrder: number;
+    openedAt: string | null;
+    signedAt: string | null;
+    hasSigned: boolean;
+    /** `null` until the document has been sent. */
+    signUrl: string | null;
+    advanced?: {
+        signaturePlacement: SignaturePlacement;
+    };
+}
+/** Response of `GET /api/v1/documents/{documentId}`. */
+interface Document {
+    documentId: string;
+    name: string;
+    status: DocumentStatus;
+    createdAt: string;
+    updatedAt: string;
+    completedAt: string | null;
+    /** Temporary presigned link to the signed PDF, set once `COMPLETED`. */
+    downloadUrl: string | null;
+    /** Bearer-authenticated certificate endpoint, set once `COMPLETED`. */
+    certificateUrl: string | null;
+    signers: DocumentSigner[];
+}
+interface AddedSigner {
+    signerId: string;
+    name: string;
+    email: string | null;
+    signingOrder: number;
+    advanced?: {
+        signaturePlacement: SignaturePlacement;
+    };
+}
+/** Response of `POST /api/v1/documents/{documentId}/signers`. */
+interface AddSignersResponse {
+    signers: AddedSigner[];
+}
+interface SentSigner {
+    signerId: string;
+    name: string;
+    email: string | null;
+    signingOrder: number;
+    signUrl: string;
+}
+/** Response of `POST /api/v1/documents/{documentId}/send`. */
+interface SendDocumentResponse {
+    documentId: string;
+    status: "SENT";
+    creditsRemaining: number;
+    signers: SentSigner[];
+}
+/** Error body returned by every failing API call. */
+interface ApiErrorBody {
+    error: string;
+    message: string;
+}
+type WebhookEventType = "signer.signed" | "document.completed";
+interface WebhookSigner {
+    signerId: string;
+    name: string;
+    email: string | null;
+    signingOrder: number;
+    signedAt: string | null;
+    hasSigned: boolean;
+}
+interface SignerSignedEvent {
+    event: "signer.signed";
+    documentId: string;
+    status: DocumentStatus;
+    occurredAt: string;
+    /** The signer who just signed. */
+    signer: WebhookSigner | null;
+    signers: WebhookSigner[];
+}
+interface DocumentCompletedEvent {
+    event: "document.completed";
+    documentId: string;
+    status: DocumentStatus;
+    occurredAt: string;
+    completedAt: string | null;
+    certificateUrl: string;
+    signers: WebhookSigner[];
+}
+type WebhookEvent = SignerSignedEvent | DocumentCompletedEvent;
+
+/** Header carrying the signature, `sha256=<hex>`. */
+declare const SIGNATURE_HEADER = "X-SignSetu-Signature";
+/** Header carrying the event type, for example `signer.signed`. */
+declare const EVENT_HEADER = "X-SignSetu-Event";
+type WebhookPayload = string | Uint8Array | ArrayBuffer;
+/** Computes the `sha256=<hex>` header value SignYu sends for a raw body. */
+declare function computeSignature(payload: WebhookPayload, secret: string): string;
+/**
+ * Returns true when `signatureHeader` (the `X-SignSetu-Signature` value) is a
+ * valid HMAC-SHA256 of the raw request body under `secret`. Pass the raw body
+ * bytes exactly as received; a re-serialized object will not match.
+ * Comparison is constant time.
+ */
+declare function verifySignature(payload: WebhookPayload, signatureHeader: string | null | undefined, secret: string): boolean;
+/**
+ * Verifies the signature and returns the parsed event. Throws
+ * `WebhookSignatureError` if the signature is missing or invalid.
+ */
+declare function constructEvent(payload: WebhookPayload, signatureHeader: string | null | undefined, secret: string): WebhookEvent;
+declare const webhooks: {
+    SIGNATURE_HEADER: string;
+    EVENT_HEADER: string;
+    computeSignature: typeof computeSignature;
+    verifySignature: typeof verifySignature;
+    constructEvent: typeof constructEvent;
+};
+type Webhooks = typeof webhooks;
+
+declare const DEFAULT_BASE_URL = "https://signyu.com";
+interface SignYuOptions {
+    /** Your secret API key, `sk_live_...`. Keep it server side. */
+    apiKey: string;
+    /** Defaults to `https://signyu.com`. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Defaults to 60000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+}
+type FileInput = Blob | Uint8Array | ArrayBuffer;
+interface CreateDocumentParams {
+    /** The PDF to sign, at most 10MB. A Node.js `Buffer` works here. */
+    file: FileInput;
+    /** File name sent with the upload. Defaults to `document.pdf`. */
+    fileName?: string;
+    /** Label for the document. Defaults to the file name. */
+    name?: string;
+}
+interface ListDocumentsParams {
+    /** 1 to 100, default 20. */
+    limit?: number;
+    /** Default 0. */
+    offset?: number;
+}
+interface RequestOptions {
+    method: "GET" | "POST";
+    path: string;
+    query?: Record<string, string | number | undefined>;
+    body?: BodyInit;
+    json?: unknown;
+    expect?: "json" | "binary";
+}
+declare class Documents {
+    private readonly client;
+    constructor(client: SignYu);
+    /** `POST /api/v1/documents`: upload a PDF and create a `PENDING` document. */
+    create(params: CreateDocumentParams): Promise<CreatedDocument>;
+    /** `GET /api/v1/documents`: your documents, most recent first. */
+    list(params?: ListDocumentsParams): Promise<DocumentList>;
+    /** `GET /api/v1/documents/{documentId}`: status and per-signer progress. */
+    get(documentId: string): Promise<Document>;
+    /** `POST /api/v1/documents/{documentId}/signers`: add signers while `PENDING` (max 6 per document). */
+    addSigners(documentId: string, signers: SignerInput[]): Promise<AddSignersResponse>;
+    /**
+     * `POST /api/v1/documents/{documentId}/send`: deducts one credit per signer,
+     * emails signing links and returns them. Not idempotent: call it once.
+     */
+    send(documentId: string): Promise<SendDocumentResponse>;
+    /**
+     * `GET /api/v1/documents/{documentId}/certificate`: the completion
+     * certificate and audit trail PDF as raw bytes. Only available once the
+     * document is `COMPLETED` (otherwise `409 invalid_state`).
+     */
+    getCertificate(documentId: string): Promise<Uint8Array>;
+}
+declare class SignYu {
+    readonly documents: Documents;
+    readonly webhooks: Webhooks;
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: SignYuOptions);
+    /** @internal */
+    _request<T>(opts: RequestOptions): Promise<T>;
+}
+
+/**
+ * Thrown for any non-2xx API response, network failure or timeout.
+ *
+ * `code` is the API's machine readable `error` field (for example
+ * `insufficient_credits`). For responses without a JSON error body it is
+ * `rate_limited` (429) or `http_error`; for network failures it is
+ * `connection_error` and for timeouts `timeout`, both with `status` 0.
+ */
+declare class SignYuError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** Parsed response body, when there was one. */
+    readonly body: unknown;
+    constructor(opts: {
+        status: number;
+        code: string;
+        message: string;
+        body?: unknown;
+        cause?: unknown;
+    });
+}
+/** Thrown by `webhooks.constructEvent` when the signature does not match. */
+declare class WebhookSignatureError extends Error {
+    constructor(message?: string);
+}
+
+declare const VERSION = "0.1.0";
+
+export { type AddSignersResponse, type AddedSigner, type ApiErrorBody, type CreateDocumentParams, type CreatedDocument, DEFAULT_BASE_URL, type Document, type DocumentCompletedEvent, type DocumentList, type DocumentSigner, type DocumentStatus, type DocumentSummary, Documents, EVENT_HEADER, type FileInput, type ListDocumentsParams, SIGNATURE_HEADER, type SendDocumentResponse, type SentSigner, SignYu, SignYuError, type SignYuOptions, type SignaturePlacement, type SignaturePosition, type SignerAdvanced, type SignerCounts, type SignerInput, type SignerSignedEvent, VERSION, type WebhookEvent, type WebhookEventType, type WebhookPayload, WebhookSignatureError, type WebhookSigner, type Webhooks, computeSignature, constructEvent, verifySignature, webhooks };

package/dist/index.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Types mirroring the SignYu REST API (src/app/api/v1/** in the SignYu repo).
+ * Timestamps are ISO 8601 strings as returned in JSON.
+ */
+/** Document lifecycle state. `PENDING` until sent, `SENT` while out for signature, `COMPLETED` when every signer has signed. */
+type DocumentStatus = "PENDING" | "SENT" | "COMPLETED" | "FAILED" | "CANCELLED" | (string & {});
+/** One stamp rectangle in PDF points, origin at the bottom-left of the page. */
+interface SignaturePosition {
+    /** 1-based page index. */
+    page: number;
+    /** Left edge in PDF points. */
+    x: number;
+    /** Bottom edge in PDF points (origin is bottom-left). */
+    y: number;
+    /** Box width in PDF points (minimum 140). */
+    width: number;
+    /** Box height in PDF points (minimum 110). */
+    height: number;
+}
+interface SignaturePlacement {
+    /** One rectangle per page, 1 to 20 entries, pages must be distinct. */
+    positions: SignaturePosition[];
+}
+interface SignerAdvanced {
+    signaturePlacement?: SignaturePlacement;
+}
+interface SignerInput {
+    /** Signer's full name. */
+    name: string;
+    /** Digits only, at least 10 characters. */
+    phone: string;
+    /** Valid email address. The signing link is emailed here. */
+    email: string;
+    /** Optional custom stamp placement. Omit to use the default fixed slot. */
+    advanced?: SignerAdvanced;
+}
+/** Response of `POST /api/v1/documents`. */
+interface CreatedDocument {
+    documentId: string;
+    name: string;
+    status: DocumentStatus;
+}
+interface SignerCounts {
+    total: number;
+    signed: number;
+}
+interface DocumentSummary {
+    documentId: string;
+    name: string;
+    status: DocumentStatus;
+    createdAt: string;
+    signers: SignerCounts;
+}
+/** Response of `GET /api/v1/documents`. */
+interface DocumentList {
+    documents: DocumentSummary[];
+    limit: number;
+    offset: number;
+}
+interface DocumentSigner {
+    signerId: string;
+    name: string;
+    email: string | null;
+    phone: string;
+    signingOrder: number;
+    openedAt: string | null;
+    signedAt: string | null;
+    hasSigned: boolean;
+    /** `null` until the document has been sent. */
+    signUrl: string | null;
+    advanced?: {
+        signaturePlacement: SignaturePlacement;
+    };
+}
+/** Response of `GET /api/v1/documents/{documentId}`. */
+interface Document {
+    documentId: string;
+    name: string;
+    status: DocumentStatus;
+    createdAt: string;
+    updatedAt: string;
+    completedAt: string | null;
+    /** Temporary presigned link to the signed PDF, set once `COMPLETED`. */
+    downloadUrl: string | null;
+    /** Bearer-authenticated certificate endpoint, set once `COMPLETED`. */
+    certificateUrl: string | null;
+    signers: DocumentSigner[];
+}
+interface AddedSigner {
+    signerId: string;
+    name: string;
+    email: string | null;
+    signingOrder: number;
+    advanced?: {
+        signaturePlacement: SignaturePlacement;
+    };
+}
+/** Response of `POST /api/v1/documents/{documentId}/signers`. */
+interface AddSignersResponse {
+    signers: AddedSigner[];
+}
+interface SentSigner {
+    signerId: string;
+    name: string;
+    email: string | null;
+    signingOrder: number;
+    signUrl: string;
+}
+/** Response of `POST /api/v1/documents/{documentId}/send`. */
+interface SendDocumentResponse {
+    documentId: string;
+    status: "SENT";
+    creditsRemaining: number;
+    signers: SentSigner[];
+}
+/** Error body returned by every failing API call. */
+interface ApiErrorBody {
+    error: string;
+    message: string;
+}
+type WebhookEventType = "signer.signed" | "document.completed";
+interface WebhookSigner {
+    signerId: string;
+    name: string;
+    email: string | null;
+    signingOrder: number;
+    signedAt: string | null;
+    hasSigned: boolean;
+}
+interface SignerSignedEvent {
+    event: "signer.signed";
+    documentId: string;
+    status: DocumentStatus;
+    occurredAt: string;
+    /** The signer who just signed. */
+    signer: WebhookSigner | null;
+    signers: WebhookSigner[];
+}
+interface DocumentCompletedEvent {
+    event: "document.completed";
+    documentId: string;
+    status: DocumentStatus;
+    occurredAt: string;
+    completedAt: string | null;
+    certificateUrl: string;
+    signers: WebhookSigner[];
+}
+type WebhookEvent = SignerSignedEvent | DocumentCompletedEvent;
+
+/** Header carrying the signature, `sha256=<hex>`. */
+declare const SIGNATURE_HEADER = "X-SignSetu-Signature";
+/** Header carrying the event type, for example `signer.signed`. */
+declare const EVENT_HEADER = "X-SignSetu-Event";
+type WebhookPayload = string | Uint8Array | ArrayBuffer;
+/** Computes the `sha256=<hex>` header value SignYu sends for a raw body. */
+declare function computeSignature(payload: WebhookPayload, secret: string): string;
+/**
+ * Returns true when `signatureHeader` (the `X-SignSetu-Signature` value) is a
+ * valid HMAC-SHA256 of the raw request body under `secret`. Pass the raw body
+ * bytes exactly as received; a re-serialized object will not match.
+ * Comparison is constant time.
+ */
+declare function verifySignature(payload: WebhookPayload, signatureHeader: string | null | undefined, secret: string): boolean;
+/**
+ * Verifies the signature and returns the parsed event. Throws
+ * `WebhookSignatureError` if the signature is missing or invalid.
+ */
+declare function constructEvent(payload: WebhookPayload, signatureHeader: string | null | undefined, secret: string): WebhookEvent;
+declare const webhooks: {
+    SIGNATURE_HEADER: string;
+    EVENT_HEADER: string;
+    computeSignature: typeof computeSignature;
+    verifySignature: typeof verifySignature;
+    constructEvent: typeof constructEvent;
+};
+type Webhooks = typeof webhooks;
+
+declare const DEFAULT_BASE_URL = "https://signyu.com";
+interface SignYuOptions {
+    /** Your secret API key, `sk_live_...`. Keep it server side. */
+    apiKey: string;
+    /** Defaults to `https://signyu.com`. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Defaults to 60000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+}
+type FileInput = Blob | Uint8Array | ArrayBuffer;
+interface CreateDocumentParams {
+    /** The PDF to sign, at most 10MB. A Node.js `Buffer` works here. */
+    file: FileInput;
+    /** File name sent with the upload. Defaults to `document.pdf`. */
+    fileName?: string;
+    /** Label for the document. Defaults to the file name. */
+    name?: string;
+}
+interface ListDocumentsParams {
+    /** 1 to 100, default 20. */
+    limit?: number;
+    /** Default 0. */
+    offset?: number;
+}
+interface RequestOptions {
+    method: "GET" | "POST";
+    path: string;
+    query?: Record<string, string | number | undefined>;
+    body?: BodyInit;
+    json?: unknown;
+    expect?: "json" | "binary";
+}
+declare class Documents {
+    private readonly client;
+    constructor(client: SignYu);
+    /** `POST /api/v1/documents`: upload a PDF and create a `PENDING` document. */
+    create(params: CreateDocumentParams): Promise<CreatedDocument>;
+    /** `GET /api/v1/documents`: your documents, most recent first. */
+    list(params?: ListDocumentsParams): Promise<DocumentList>;
+    /** `GET /api/v1/documents/{documentId}`: status and per-signer progress. */
+    get(documentId: string): Promise<Document>;
+    /** `POST /api/v1/documents/{documentId}/signers`: add signers while `PENDING` (max 6 per document). */
+    addSigners(documentId: string, signers: SignerInput[]): Promise<AddSignersResponse>;
+    /**
+     * `POST /api/v1/documents/{documentId}/send`: deducts one credit per signer,
+     * emails signing links and returns them. Not idempotent: call it once.
+     */
+    send(documentId: string): Promise<SendDocumentResponse>;
+    /**
+     * `GET /api/v1/documents/{documentId}/certificate`: the completion
+     * certificate and audit trail PDF as raw bytes. Only available once the
+     * document is `COMPLETED` (otherwise `409 invalid_state`).
+     */
+    getCertificate(documentId: string): Promise<Uint8Array>;
+}
+declare class SignYu {
+    readonly documents: Documents;
+    readonly webhooks: Webhooks;
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: SignYuOptions);
+    /** @internal */
+    _request<T>(opts: RequestOptions): Promise<T>;
+}
+
+/**
+ * Thrown for any non-2xx API response, network failure or timeout.
+ *
+ * `code` is the API's machine readable `error` field (for example
+ * `insufficient_credits`). For responses without a JSON error body it is
+ * `rate_limited` (429) or `http_error`; for network failures it is
+ * `connection_error` and for timeouts `timeout`, both with `status` 0.
+ */
+declare class SignYuError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** Parsed response body, when there was one. */
+    readonly body: unknown;
+    constructor(opts: {
+        status: number;
+        code: string;
+        message: string;
+        body?: unknown;
+        cause?: unknown;
+    });
+}
+/** Thrown by `webhooks.constructEvent` when the signature does not match. */
+declare class WebhookSignatureError extends Error {
+    constructor(message?: string);
+}
+
+declare const VERSION = "0.1.0";
+
+export { type AddSignersResponse, type AddedSigner, type ApiErrorBody, type CreateDocumentParams, type CreatedDocument, DEFAULT_BASE_URL, type Document, type DocumentCompletedEvent, type DocumentList, type DocumentSigner, type DocumentStatus, type DocumentSummary, Documents, EVENT_HEADER, type FileInput, type ListDocumentsParams, SIGNATURE_HEADER, type SendDocumentResponse, type SentSigner, SignYu, SignYuError, type SignYuOptions, type SignaturePlacement, type SignaturePosition, type SignerAdvanced, type SignerCounts, type SignerInput, type SignerSignedEvent, VERSION, type WebhookEvent, type WebhookEventType, type WebhookPayload, WebhookSignatureError, type WebhookSigner, type Webhooks, computeSignature, constructEvent, verifySignature, webhooks };