@uveysservetoglu/kobil-sign 1.0.0

package/README.md

@@ -0,0 +1,51 @@
+# @uveysservetoglu/kobil-sign
+
+KOBIL digital signature client for Node.js / TypeScript, with automatic OAuth token management.
+
+```bash
+npm install @uveysservetoglu/kobil-sign
+```
+
+```ts
+import { SignClient } from "@uveysservetoglu/kobil-sign";
+
+const sign = new SignClient({
+  // credentials (or KOBIL_* env vars):
+  tokenEndpoint: process.env.KOBIL_TOKEN_ENDPOINT!,
+  clientId: process.env.KOBIL_CLIENT_ID!,
+  clientSecret: process.env.KOBIL_CLIENT_SECRET!,
+  // sign-specific:
+  signBaseUrl: "https://idp.cloud.kobil.com/auth/realms/{TENANT}/mpower/v1/users/{USER_ID}",
+  tenantName: "acme",
+  defaultCallbackUrl: "https://yourapi.com/signature-callback",
+});
+
+const res = await sign.initiatePdfSignature({
+  userId,
+  file: pdfBytes,
+  fileName: "Agreement.pdf",
+  messageText: "Please sign here",
+  position: { pageNumber: 1, bottomLeftX: 59, bottomLeftY: 89, topRightX: 85, topRightY: 96 },
+});
+// res.messageId, res.instanceId
+```
+
+`{TENANT}` is filled from `tenantName`, `{USER_ID}` from the call; `/signature` is appended.
+
+### How it maps to the API
+
+`POST {signBaseUrl}/signature` as `multipart/form-data`:
+
+- `signatureFile` — the PDF bytes (`application/pdf`)
+- `signatureData` — JSON: `version`, `pageNumber`, `bottomLeft*/topRight*Coordinate`,
+  `serviceUuid`, `messageText`, `callbackUrl`
+
+The signed PDF is delivered to your callback as a `signatureResponse`; download it by its
+`mediaId` using `@uveysservetoglu/kobil-chat`'s `getAttachmentFile`.
+
+JavaScript usage is identical (`const { SignClient } = require("@uveysservetoglu/kobil-sign")`).
+Failures throw `KobilSignError` (extends `KobilError`).
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,30 @@
+import { KobilCredentials, KobilError, KobilServiceClient, TokenProvider } from "@uveysservetoglu/kobil-core";
+import { InitiateSignatureInput, SignatureResult } from "./types";
+export interface SignClientOptions extends Partial<KobilCredentials> {
+    /** Signature endpoint template up to the user segment, with {TENANT} and {USER_ID}. */
+    signBaseUrl: string;
+    /** Tenant/realm name substituted for {TENANT}. */
+    tenantName?: string;
+    /** serviceUuid sent with the request. Optional: defaults to clientId. */
+    serviceUuid?: string;
+    /** Default callback URL for signature results; overridable per request. */
+    defaultCallbackUrl?: string;
+    /** Wire protocol version. Default: 3. */
+    version?: number;
+    tokenProvider?: TokenProvider;
+}
+/** Client for the KOBIL digital signature API. */
+export declare class SignClient extends KobilServiceClient {
+    private readonly signBaseUrl;
+    private readonly tenantName?;
+    private readonly clientId;
+    private readonly serviceUuidOption?;
+    private readonly defaultCallbackUrl?;
+    private readonly version;
+    constructor(options: SignClientOptions);
+    protected makeError(message: string, statusCode?: number, responseBody?: string, cause?: unknown): KobilError;
+    initiatePdfSignature(input: InitiateSignatureInput, signal?: AbortSignal): Promise<SignatureResult>;
+    private signatureUrl;
+    private serviceUuid;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,aAAa,EAEd,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAElE,MAAM,WAAW,iBAAkB,SAAQ,OAAO,CAAC,gBAAgB,CAAC;IAClE,uFAAuF;IACvF,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,kDAAkD;AAClD,qBAAa,UAAW,SAAQ,kBAAkB;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,iBAAiB;cAqBnB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,UAAU;IAItH,oBAAoB,CAAC,KAAK,EAAE,sBAAsB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;IAwBnG,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,WAAW;CAGpB"}

package/dist/client.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignClient = void 0;
+const kobil_core_1 = require("@uveysservetoglu/kobil-core");
+const error_1 = require("./error");
+/** Client for the KOBIL digital signature API. */
+class SignClient extends kobil_core_1.KobilServiceClient {
+    signBaseUrl;
+    tenantName;
+    clientId;
+    serviceUuidOption;
+    defaultCallbackUrl;
+    version;
+    constructor(options) {
+        const credentials = (0, kobil_core_1.credentialsFromEnv)({
+            tokenEndpoint: options.tokenEndpoint,
+            clientId: options.clientId,
+            clientSecret: options.clientSecret,
+            tokenAuthMode: options.tokenAuthMode,
+            defaultTokenTtlSeconds: options.defaultTokenTtlSeconds,
+            tokenExpirySkewSeconds: options.tokenExpirySkewSeconds,
+        });
+        super(options.tokenProvider ?? new kobil_core_1.DefaultTokenProvider(credentials));
+        if (!options.signBaseUrl)
+            throw new kobil_core_1.KobilError("signBaseUrl is required.");
+        this.signBaseUrl = options.signBaseUrl;
+        this.tenantName = options.tenantName;
+        this.clientId = credentials.clientId;
+        this.serviceUuidOption = options.serviceUuid;
+        this.defaultCallbackUrl = options.defaultCallbackUrl;
+        this.version = options.version ?? 3;
+    }
+    makeError(message, statusCode, responseBody, cause) {
+        return new error_1.KobilSignError(message, { statusCode, responseBody, cause });
+    }
+    initiatePdfSignature(input, signal) {
+        if (!input.userId)
+            throw new error_1.KobilSignError("userId cannot be empty.");
+        if (!input.file || input.file.length === 0)
+            throw new error_1.KobilSignError("file (PDF) cannot be empty.");
+        const p = input.position;
+        const signatureData = {
+            version: this.version,
+            pageNumber: p.pageNumber ?? 1,
+            bottomLeftXCoordinate: p.bottomLeftX,
+            bottomLeftYCoordinate: p.bottomLeftY,
+            topRightXCoordinate: p.topRightX,
+            topRightYCoordinate: p.topRightY,
+            serviceUuid: this.serviceUuid(),
+            messageText: input.messageText,
+            callbackUrl: input.callbackUrl ?? this.defaultCallbackUrl,
+        };
+        const form = new FormData();
+        form.append("signatureFile", new Blob([input.file], { type: "application/pdf" }), input.fileName ?? "document.pdf");
+        form.append("signatureData", JSON.stringify(signatureData));
+        return this.send("POST", this.signatureUrl(input.userId), form, signal);
+    }
+    signatureUrl(userId) {
+        const base = replaceTokens(this.signBaseUrl, { "{TENANT}": this.tenantName, "{USER_ID}": userId }).replace(/\/+$/, "");
+        return `${base}/signature`;
+    }
+    serviceUuid() {
+        return this.serviceUuidOption && this.serviceUuidOption.length > 0 ? this.serviceUuidOption : this.clientId;
+    }
+}
+exports.SignClient = SignClient;
+function replaceTokens(template, tokens) {
+    let result = template;
+    for (const [token, value] of Object.entries(tokens)) {
+        result = result.split(token).join(encodeURIComponent(value ?? ""));
+    }
+    return result;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AAAA,4DAOqC;AACrC,mCAAyC;AAiBzC,kDAAkD;AAClD,MAAa,UAAW,SAAQ,+BAAkB;IAC/B,WAAW,CAAS;IACpB,UAAU,CAAU;IACpB,QAAQ,CAAS;IACjB,iBAAiB,CAAU;IAC3B,kBAAkB,CAAU;IAC5B,OAAO,CAAS;IAEjC,YAAY,OAA0B;QACpC,MAAM,WAAW,GAAG,IAAA,+BAAkB,EAAC;YACrC,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;YACtD,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;SACvD,CAAC,CAAC;QACH,KAAK,CAAC,OAAO,CAAC,aAAa,IAAI,IAAI,iCAAoB,CAAC,WAAW,CAAC,CAAC,CAAC;QAEtE,IAAI,CAAC,OAAO,CAAC,WAAW;YAAE,MAAM,IAAI,uBAAU,CAAC,0BAA0B,CAAC,CAAC;QAE3E,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC;QACrC,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;QAC7C,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;QACrD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;IACtC,CAAC;IAEkB,SAAS,CAAC,OAAe,EAAE,UAAmB,EAAE,YAAqB,EAAE,KAAe;QACvG,OAAO,IAAI,sBAAc,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,oBAAoB,CAAC,KAA6B,EAAE,MAAoB;QACtE,IAAI,CAAC,KAAK,CAAC,MAAM;YAAE,MAAM,IAAI,sBAAc,CAAC,yBAAyB,CAAC,CAAC;QACvE,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,sBAAc,CAAC,6BAA6B,CAAC,CAAC;QAEpG,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC;QACzB,MAAM,aAAa,GAAG;YACpB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,CAAC;YAC7B,qBAAqB,EAAE,CAAC,CAAC,WAAW;YACpC,qBAAqB,EAAE,CAAC,CAAC,WAAW;YACpC,mBAAmB,EAAE,CAAC,CAAC,SAAS;YAChC,mBAAmB,EAAE,CAAC,CAAC,SAAS;YAChC,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE;YAC/B,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,IAAI,CAAC,kBAAkB;SAC1D,CAAC;QAEF,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,EAAE,KAAK,CAAC,QAAQ,IAAI,cAAc,CAAC,CAAC;QACpH,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;QAE5D,OAAO,IAAI,CAAC,IAAI,CAAkB,MAAM,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3F,CAAC;IAEO,YAAY,CAAC,MAAc;QACjC,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACvH,OAAO,GAAG,IAAI,YAAY,CAAC;IAC7B,CAAC;IAEO,WAAW;QACjB,OAAO,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC;IAC9G,CAAC;CACF;AAjED,gCAiEC;AAED,SAAS,aAAa,CAAC,QAAgB,EAAE,MAA0C;IACjF,IAAI,MAAM,GAAG,QAAQ,CAAC;IACtB,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACpD,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/error.d.ts

@@ -0,0 +1,5 @@
+import { KobilError } from "@uveysservetoglu/kobil-core";
+/** Thrown when a signature operation fails. */
+export declare class KobilSignError extends KobilError {
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,+CAA+C;AAC/C,qBAAa,cAAe,SAAQ,UAAU;CAAG"}

package/dist/error.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KobilSignError = void 0;
+const kobil_core_1 = require("@uveysservetoglu/kobil-core");
+/** Thrown when a signature operation fails. */
+class KobilSignError extends kobil_core_1.KobilError {
+}
+exports.KobilSignError = KobilSignError;
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":";;;AAAA,4DAAyD;AAEzD,+CAA+C;AAC/C,MAAa,cAAe,SAAQ,uBAAU;CAAG;AAAjD,wCAAiD"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { SignClient } from "./client";
+export type { SignClientOptions } from "./client";
+export { KobilSignError } from "./error";
+export type { InitiateSignatureInput, SignaturePosition, SignatureResult } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,YAAY,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KobilSignError = exports.SignClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "SignClient", { enumerable: true, get: function () { return client_1.SignClient; } });
+var error_1 = require("./error");
+Object.defineProperty(exports, "KobilSignError", { enumerable: true, get: function () { return error_1.KobilSignError; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAAsC;AAA7B,oGAAA,UAAU,OAAA;AAEnB,iCAAyC;AAAhC,uGAAA,cAAc,OAAA"}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+/** Rectangle (in PDF points) where the signature is placed on a page. */
+export interface SignaturePosition {
+    /** 1-based page number. Default: 1. */
+    pageNumber?: number;
+    bottomLeftX: number;
+    bottomLeftY: number;
+    topRightX: number;
+    topRightY: number;
+}
+export interface InitiateSignatureInput {
+    userId: string;
+    /** Raw PDF bytes to be signed. */
+    file: Uint8Array;
+    /** File name for the upload part. Default: "document.pdf". */
+    fileName?: string;
+    /** Prompt shown to the signer. */
+    messageText?: string;
+    /** Callback URL for the signature result. Falls back to the configured default. */
+    callbackUrl?: string;
+    position: SignaturePosition;
+}
+export interface SignatureResult {
+    messageId?: string;
+    instanceId?: string;
+    [key: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@uveysservetoglu/kobil-sign",
+  "version": "1.0.0",
+  "description": "KOBIL digital signature client for Node.js: initiate PDF signatures with automatic OAuth token management.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "kobil",
+    "signature",
+    "pdf",
+    "esign"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uveysservetoglu/kobil-sdks"
+  },
+  "dependencies": {
+    "@uveysservetoglu/kobil-core": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}