instasign 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-02-27
+
+### Added
+- Initial release of the `instasign-api-sdk`.
+- **Stripe-inspired API**: High-quality, resource-based orientation (`instasign.envelopes.create()`).
+- **Extended Envelopes API**: Added `get`, `updateMetadata`, `addSignRequest`, `addSignRequests`, and `removeSignRequest`.
+- **SignRequests API Improvements**: Added `getFile` to retrieve file metadata from a request ID.
+- **Enhanced Configuration**: Added support for both `apiKey` (Dashboard API) and `restApiKey` (Parse REST API).
+- **Webhook Support**: Dedicated `Webhooks` class with `constructEvent` for secure signature verification.
+- **Strict Typing**: Integrated `schema.d.ts` generated from OpenAPI specification for 100% type safety.
+- **Deep Type Inference**: Improved Swagger generator to extract nested properties for cloud function results.
+- **Configurable Tolerance**: Webhook signature verification now supports a configurable `webhookTolerance` (defaulting to 300s).
+- **Public API Filtering**: Automatically excludes internal/sensitive cloud functions (e.g., `createApiKey`, `db-migrate`) from the SDK surface.

package/README.md

@@ -0,0 +1,122 @@
+# Instasign Node.js SDK
+
+The **Instasign Node.js SDK** provides convenient access to the **Instasign Service** from applications written in server-side JavaScript or TypeScript. It is designed to simplify document signing workflows by providing a high-level, promise-based API for creating envelopes, managing sign requests, and verifying webhooks.
+
+> [!CAUTION]
+> **Security Warning:** While this library can technically be used in client-side (frontend) applications, it is **strongly discouraged** for security reasons. Using the SDK on the frontend requires you to expose your Instasign API key, which could be stolen by anyone visiting your site. For production applications, always perform Instasign API calls from a secure server-side environment.
+
+## Installation
+
+Install the package with:
+
+```bash
+npm install instasign-api-sdk
+```
+
+## Usage
+
+The package needs to be configured with your account's API key.
+
+```typescript
+import { Instasign } from 'instasign-api-sdk';
+
+const instasign = new Instasign({
+  apiKey: 'your_api_key',
+  restApiKey: 'your_parse_rest_api_key', // Optional
+  serverUrl: 'https://parseapi.back4app.com', // Optional
+  appId: 'your_app_id', // Optional
+  webhookTolerance: 300 // default is 300 seconds (5 minutes)
+});
+```
+
+### Envelopes
+
+Envelopes are containers for one or more documents that need to be signed.
+
+```typescript
+// Create an envelope
+const envelope = await instasign.envelopes.create({
+  name: 'Service Agreement',
+  description: 'Please sign the attached document',
+});
+
+// List envelopes
+const envelopes = await instasign.envelopes.list();
+
+// Retrieve an envelope by ID
+const envelope = await instasign.envelopes.get('envelope_id_here');
+
+// Update envelope metadata
+await instasign.envelopes.updateMetadata({
+  envelopeId: 'envelope_id_here',
+  metadata: { customField: 'value' }
+});
+
+// Add a sign request to an envelope
+await instasign.envelopes.addSignRequest({
+  envelopeId: 'envelope_id_here',
+  filename: 'contract.pdf',
+  base64File: '...'
+});
+
+// Delete an envelope
+await instasign.envelopes.delete('envelope_id_here');
+```
+
+### Sign Requests
+
+Manage individual signature requests.
+
+```typescript
+// Create a sign request
+const signRequest = await instasign.signRequests.create({
+  filename: 'contract.pdf',
+  base64File: '...', // base64 encoded file content
+});
+
+// Retrieve file data
+const fileData = await instasign.signRequests.getFile('request_id_here');
+
+// Complete a sign request
+await instasign.signRequests.complete({
+  requestId: 'request_id_here',
+  signedFileDataBase64: '...'
+});
+```
+
+### Webhooks
+
+Instasign can send webhook events to your server. Use the `webhooks` resource to verify signature headers securely.
+
+```typescript
+const payload = req.body; // Raw request body
+const sig = req.headers['x-instasign-signature'];
+const endpointSecret = 'secret_key';
+
+try {
+  const event = instasign.webhooks.constructEvent(payload, sig, endpointSecret);
+  // Handle the event
+  console.log(event.type);
+} catch (err) {
+  console.error(`Webhook Error: ${err.message}`);
+  res.status(400).send(`Webhook Error: ${err.message}`);
+}
+```
+
+## TypeScript Support
+
+This library is built with TypeScript and provides industry-standard type definitions auto-generated from the Instasign OpenAPI schema. Every method in the SDK is strictly typed, ensuring you catch errors at compile time and get excellent IDE autocompletion.
+
+## Configuration Options
+
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `apiKey` | `string` | **Required**. Your Instasign Dashboard API Key (passed in `x-api-key` header). |
+| `restApiKey` | `string` | Optional. Your Parse REST API Key (passed in `X-Parse-REST-API-KEY` header). |
+| `serverUrl` | `string` | Optional. Base URL for the Parse Server (defaults to Back4App). |
+| `appId` | `string` | Optional. Your Parse Application ID. |
+| `webhookTolerance` | `number` | Optional. Allowed time drift for webhook signatures in seconds (default: 300). |
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { Envelopes } from './resources/Envelopes.js';
+import { SignRequests } from './resources/SignRequests.js';
+import { Webhooks } from './resources/Webhooks.js';
+export interface IInstasignConfig {
+    apiKey: string;
+    appId?: string;
+    restApiKey?: string;
+    serverUrl?: string;
+    webhookTolerance?: number;
+}
+export declare class Instasign {
+    private client;
+    envelopes: Envelopes;
+    signRequests: SignRequests;
+    webhooks: Webhooks;
+    constructor(config: IInstasignConfig);
+}

package/dist/index.js

@@ -0,0 +1,24 @@
+import axios from 'axios';
+import { Envelopes } from './resources/Envelopes.js';
+import { SignRequests } from './resources/SignRequests.js';
+import { Webhooks } from './resources/Webhooks.js';
+export class Instasign {
+    client;
+    envelopes;
+    signRequests;
+    webhooks;
+    constructor(config) {
+        this.client = axios.create({
+            baseURL: config.serverUrl || 'https://parseapi.back4app.com',
+            headers: {
+                'X-Parse-APPLICATION-ID': config.appId || 'jKFo8BFQRdiAUV4F3o3SIDWLpLUb2TVW7bVl7lwH',
+                'X-Parse-REST-API-KEY': config.restApiKey || 'Gjm9pmxZh0DjXHkcFlf0kGZjHfYEY4ERw71TvLig',
+                'x-api-key': config.apiKey,
+                'Content-Type': 'application/json',
+            },
+        });
+        this.envelopes = new Envelopes(this.client);
+        this.signRequests = new SignRequests(this.client);
+        this.webhooks = new Webhooks(config.webhookTolerance ?? 300);
+    }
+}

package/dist/resources/Envelopes.d.ts

@@ -0,0 +1,58 @@
+import { AxiosInstance } from 'axios';
+import { paths } from '../schema.js';
+type CreateEnvelopeParams = NonNullable<paths["/functions/createEnvelope"]["post"]["requestBody"]>["content"]["application/json"];
+type CreateEnvelopeResponse = NonNullable<NonNullable<paths["/functions/createEnvelope"]["post"]["responses"]>["200"]["content"]>["application/json"]["result"];
+type GetEnvelopesParams = NonNullable<paths["/functions/getEnvelopes"]["post"]["requestBody"]>["content"]["application/json"];
+type GetEnvelopesResponse = NonNullable<NonNullable<paths["/functions/getEnvelopes"]["post"]["responses"]>["200"]["content"]>["application/json"]["result"];
+type GetEnvelopeResponse = NonNullable<NonNullable<paths["/functions/getEnvelope"]["post"]["responses"]>["200"]["content"]>["application/json"]["result"];
+type CompleteEnvelopeResponse = NonNullable<NonNullable<paths["/functions/completeEnvelope"]["post"]["responses"]>["200"]["content"]>["application/json"]["result"];
+type DeleteEnvelopeResponse = NonNullable<NonNullable<paths["/functions/deleteEnvelope"]["post"]["responses"]>["200"]["content"]>["application/json"]["result"];
+type UpdateEnvelopeMetadataParams = NonNullable<paths["/functions/updateEnvelopeMetadata"]["post"]["requestBody"]>["content"]["application/json"];
+type UpdateEnvelopeMetadataResponse = NonNullable<NonNullable<paths["/functions/updateEnvelopeMetadata"]["post"]["responses"]>["200"]["content"]>["application/json"]["result"];
+type RemoveSignRequestFromEnvelopeParams = NonNullable<paths["/functions/removeSignRequestFromEnvelope"]["post"]["requestBody"]>["content"]["application/json"];
+type RemoveSignRequestFromEnvelopeResponse = NonNullable<NonNullable<paths["/functions/removeSignRequestFromEnvelope"]["post"]["responses"]>["200"]["content"]>["application/json"]["result"];
+type AddSignRequestToEnvelopeParams = NonNullable<paths["/functions/addSignRequestToEnvelope"]["post"]["requestBody"]>["content"]["application/json"];
+type AddSignRequestToEnvelopeResponse = NonNullable<NonNullable<paths["/functions/addSignRequestToEnvelope"]["post"]["responses"]>["200"]["content"]>["application/json"]["result"];
+type AddSignRequestsToEnvelopeParams = AddSignRequestToEnvelopeParams[];
+type AddSignRequestsToEnvelopeResponse = AddSignRequestToEnvelopeResponse[];
+export declare class Envelopes {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Create a new envelope
+     */
+    create(params: CreateEnvelopeParams): Promise<CreateEnvelopeResponse>;
+    /**
+     * List envelopes
+     */
+    list(params?: GetEnvelopesParams): Promise<GetEnvelopesResponse>;
+    /**
+     * Retrieve envelope status
+     */
+    get(envelopeId: string): Promise<GetEnvelopeResponse>;
+    /**
+     * Complete an envelope
+     */
+    complete(envelopeId: string): Promise<CompleteEnvelopeResponse>;
+    /**
+     * Delete an envelope
+     */
+    delete(envelopeId: string): Promise<DeleteEnvelopeResponse>;
+    /**
+     * Update envelope metadata
+     */
+    updateMetadata(params: UpdateEnvelopeMetadataParams): Promise<UpdateEnvelopeMetadataResponse>;
+    /**
+     * Remove sign request from envelope
+     */
+    removeSignRequest(params: RemoveSignRequestFromEnvelopeParams): Promise<RemoveSignRequestFromEnvelopeResponse>;
+    /**
+     * Add sign request to envelope
+     */
+    addSignRequest(params: AddSignRequestToEnvelopeParams): Promise<AddSignRequestToEnvelopeResponse>;
+    /**
+     * Add multiple sign request to envelope
+     */
+    addSignRequests(params: AddSignRequestsToEnvelopeParams): Promise<AddSignRequestsToEnvelopeResponse>;
+}
+export {};

package/dist/resources/Envelopes.js

@@ -0,0 +1,69 @@
+export class Envelopes {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Create a new envelope
+     */
+    async create(params) {
+        const response = await this.client.post('/functions/createEnvelope', params);
+        return response.data.result;
+    }
+    /**
+     * List envelopes
+     */
+    async list(params = {}) {
+        const response = await this.client.post('/functions/getEnvelopes', params);
+        return response.data.result;
+    }
+    /**
+     * Retrieve envelope status
+     */
+    async get(envelopeId) {
+        const response = await this.client.post('/functions/getEnvelope', { envelopeId });
+        return response.data.result;
+    }
+    /**
+     * Complete an envelope
+     */
+    async complete(envelopeId) {
+        const response = await this.client.post('/functions/completeEnvelope', { envelopeId });
+        return response.data.result;
+    }
+    /**
+     * Delete an envelope
+     */
+    async delete(envelopeId) {
+        const response = await this.client.post('/functions/deleteEnvelope', { envelopeId });
+        return response.data.result;
+    }
+    /**
+     * Update envelope metadata
+     */
+    async updateMetadata(params) {
+        const response = await this.client.post('/functions/updateEnvelopeMetadata', params);
+        return response.data.result;
+    }
+    /**
+     * Remove sign request from envelope
+     */
+    async removeSignRequest(params) {
+        const response = await this.client.post('/functions/removeSignRequestFromEnvelope', params);
+        return response.data.result;
+    }
+    /**
+     * Add sign request to envelope
+     */
+    async addSignRequest(params) {
+        const response = await this.client.post('/functions/addSignRequestToEnvelope', params);
+        return response.data.result;
+    }
+    /**
+     * Add multiple sign request to envelope
+     */
+    async addSignRequests(params) {
+        const response = await this.client.post('/functions/addMultipleSignRequestsToEnvelope', params);
+        return response.data.result;
+    }
+}

package/dist/resources/SignRequests.d.ts

@@ -0,0 +1,24 @@
+import { AxiosInstance } from 'axios';
+import { paths } from '../schema.js';
+type CreateSignRequestParams = NonNullable<paths["/functions/createSignRequest"]["post"]["requestBody"]>["content"]["application/json"];
+type CreateSignRequestResponse = NonNullable<NonNullable<paths["/functions/createSignRequest"]["post"]["responses"]>["200"]["content"]>["application/json"]["result"];
+type CompleteSignRequestParams = NonNullable<paths["/functions/completeSignRequest"]["post"]["requestBody"]>["content"]["application/json"];
+type CompleteSignRequestResponse = NonNullable<NonNullable<paths["/functions/completeSignRequest"]["post"]["responses"]>["200"]["content"]>["application/json"]["result"];
+type GetFileFromRequestIdResponse = NonNullable<NonNullable<paths["/functions/getFileFromRequestId"]["post"]["responses"]>["200"]["content"]>["application/json"]["result"];
+export declare class SignRequests {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Create a new sign request
+     */
+    create(params: CreateSignRequestParams): Promise<CreateSignRequestResponse>;
+    /**
+     * Complete a sign request
+     */
+    complete(params: CompleteSignRequestParams): Promise<CompleteSignRequestResponse>;
+    /**
+     * Get file from request id
+     */
+    getFile(requestId: string): Promise<GetFileFromRequestIdResponse>;
+}
+export {};

package/dist/resources/SignRequests.js

@@ -0,0 +1,27 @@
+export class SignRequests {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Create a new sign request
+     */
+    async create(params) {
+        const response = await this.client.post('/functions/createSignRequest', params);
+        return response.data.result;
+    }
+    /**
+     * Complete a sign request
+     */
+    async complete(params) {
+        const response = await this.client.post('/functions/completeSignRequest', params);
+        return response.data.result;
+    }
+    /**
+     * Get file from request id
+     */
+    async getFile(requestId) {
+        const response = await this.client.post('/functions/getFileFromRequestId', { requestId });
+        return response.data.result;
+    }
+}

package/dist/resources/Webhooks.d.ts

@@ -0,0 +1,8 @@
+export declare class Webhooks {
+    private tolerance;
+    constructor(tolerance?: number);
+    /**
+     * Verify and parse a webhook event
+     */
+    constructEvent(payload: string, signatureHeader: string, webhookSecret: string): any;
+}

package/dist/resources/Webhooks.js

@@ -0,0 +1,32 @@
+import crypto from 'crypto';
+export class Webhooks {
+    tolerance;
+    constructor(tolerance = 300) {
+        this.tolerance = tolerance;
+    }
+    /**
+     * Verify and parse a webhook event
+     */
+    constructEvent(payload, signatureHeader, webhookSecret) {
+        const parts = signatureHeader.split(',');
+        const timestamp = parts.find((p) => p.startsWith('t='))?.split('=')[1];
+        const signature = parts.find((p) => p.startsWith('v1='))?.split('=')[1];
+        if (!timestamp || !signature) {
+            throw new Error('Invalid signature header');
+        }
+        const now = Math.floor(Date.now() / 1000);
+        if (Math.abs(now - parseInt(timestamp)) > this.tolerance) {
+            throw new Error('Signature too old');
+        }
+        const signedPayload = `${timestamp}.${payload}`;
+        const expectedSignature = crypto
+            .createHmac('sha256', webhookSecret)
+            .update(signedPayload)
+            .digest('hex');
+        const isValid = crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
+        if (!isValid) {
+            throw new Error('Invalid signature');
+        }
+        return JSON.parse(payload);
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "instasign",
+  "version": "1.0.0",
+  "description": "Instasign API wrapper",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "instasign",
+    "digital-signature",
+    "e-signature",
+    "sdk",
+    "nodejs",
+    "typescript",
+    "document-signing"
+  ],
+  "author": "Cyberneid",
+  "contributors": [
+    "Cyberneid",
+    "Ciro Carandente"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "dependencies": {
+    "axios": "^1.12.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  }
+}