@uveysservetoglu/kobil-sign
v3.0.1
Published
KOBIL digital signature client for Node.js: initiate PDF signatures with automatic OAuth token management.
Maintainers
Readme
@uveysservetoglu/kobil-sign
KOBIL PDF signature client for Node.js / TypeScript — the MiniApp API's
/v1/messages/sendPdfSignature (default) or the legacy mPower signature API — with automatic OAuth
token management.
npm install @uveysservetoglu/kobil-signimport { SignClient } from "@uveysservetoglu/kobil-sign";
// OIDC_ISSUER, OIDC_CLIENT_ID and OIDC_CLIENT_SECRET (+ MPOWER_BASE, MPOWER_TENANT in legacy mode)
// come from the environment; only the callback is app-specific.
const sign = new SignClient({
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, plus res.createdAt and res.file (miniapp) or res.instanceId (legacy)Where the signature goes
The two APIs describe the signature box differently. Either form works in either mode — the client converts it:
| Form | Units | Origin | Fields |
|---|---|---|---|
| SignaturePosition (legacy) | integer percent of the page, 0–100 | bottom-left | pageNumber, bottomLeftX/Y, topRightX/Y |
| SignatureArea (MiniApp) | fraction of the page, 0.0–1.0 | top-left | page, left, top, width, height |
They are not PDF points. toSignatureArea / toSignaturePosition convert explicitly; legacy mode
rounds to whole percentages, because the legacy platform rejects anything else.
Several signers (miniapp mode): pass signatures instead of position — 1–20 fields, each with
its own signeeUserId (default: userId):
await sign.initiatePdfSignature({
userId,
file: pdfBytes,
messageText: "Please both sign",
signatures: [
{ position: { page: 1, left: 0.1, top: 0.85, width: 0.3, height: 0.06 } },
{ signeeUserId: otherUserId, position: { page: 1, left: 0.6, top: 0.85, width: 0.3, height: 0.06 } },
],
});Legacy mode takes exactly one field, signed by userId.
API mode
Leave apiMode unset (or KOBIL_API_MODE empty) for the MiniApp API; pass "legacy" for mPower.
See @uveysservetoglu/kobil-core for the shared settings.
| | Miniapp (default) | Legacy |
|---|---|---|
| Request | POST /v1/messages/sendPdfSignature, multipart file + JSON message | POST {signBaseUrl}/signature, multipart signatureFile + signatureData |
| messageText | required | optional |
| Callback | optional — omit for the MiniApp's global callback | callbackUrl / defaultCallbackUrl |
| Push | push bundled with the request | ignored |
Legacy mode only: the endpoint is derived from MPOWER_BASE
({base}/auth/realms/{TENANT}/mpower/v1/users/{USER_ID}, with /signature appended); {TENANT} is
filled from tenantName (MPOWER_TENANT). Pass signBaseUrl or tenantName to override.
The signed PDF is delivered to your callback; download it by its mediaId using
@uveysservetoglu/kobil-chat's getAttachmentFile.
JavaScript usage is identical (const { SignClient } = require("@uveysservetoglu/kobil-sign")).
Failures reject with KobilSignError (extends KobilError).
License
MIT
