@certysign/sdk 2.3.0 → 2.5.0

package/src/lib/SignerResource.js

@@ -0,0 +1,120 @@
+/**
+ * client.signers — the people you sign on behalf of.
+ *
+ * Signing in someone's name needs a certificate that belongs to THEM, not to your
+ * organisation. This resource covers getting them one and checking they have it:
+ *
+ *   signingStatus()  can this person sign yet, and with what
+ *   sponsor()        buy them a work certificate, funded from your wallet
+ *   resendSetup()    re-send the account-setup link if they lost it
+ *
+ * The boundary these keep: an API key can START a certificate but never FINISH one.
+ * The person proves their identity themselves, to a human reviewer. A key that could
+ * both invent a signer and obtain their certificate would produce signatures that
+ * attest to nothing.
+ */
+class SignerResource {
+  constructor(http) {
+    this._http = http;
+  }
+
+  /**
+   * Can this person sign yet, and with which certificate?
+   *
+   * Worth calling BEFORE a batch: it turns a per-document failure — discovered
+   * halfway through, after the wallet has been charged — into one answer up front.
+   *
+   * Requires `cert:status`.
+   *
+   * @param {string}  email
+   * @param {object} [opts]
+   * @param {boolean} [opts.issueCompletionUrl=false]
+   *   For a signer stuck at `AWAITING_IDENTITY_VERIFICATION`, also return a URL you
+   *   can redirect them to, so they need not hunt for the invitation email.
+   *
+   *   This MINTS A NEW LINK and the previous one stops working — including the one
+   *   already sitting in their inbox. Ask for it when you are about to redirect
+   *   someone, not on every poll. Needs `signer:sponsor`, since minting an
+   *   onboarding credential is the same class of act as sponsoring.
+   *
+   * @example
+   * const { data } = await client.signers.signingStatus('jane@example.com');
+   * if (!data.canSign) {
+   *   // data.reason is NO_SIGNING_CERTIFICATE or AWAITING_IDENTITY_VERIFICATION
+   * }
+   *
+   * @example <caption>Redirect a signer who never finished verifying</caption>
+   * const { data } = await client.signers.signingStatus(email, { issueCompletionUrl: true });
+   * if (data.pendingSponsorship?.completionUrl) {
+   *   return redirect(data.pendingSponsorship.completionUrl);
+   * }
+   */
+  signingStatus(email, { issueCompletionUrl = false } = {}) {
+    if (!email) throw new Error('signers.signingStatus: email is required');
+    const path = `/sdk/v1/signers/${encodeURIComponent(email)}/signing-status`;
+    return this._http.get(issueCompletionUrl ? `${path}?issueCompletionUrl=true` : path);
+  }
+
+  /**
+   * Sponsor a work certificate for a named person.
+   *
+   * Charges your wallet, creates the sponsorship and emails the signer. It also
+   * makes them a MEMBER of your organisation once the certificate issues — they get
+   * an account, appear in your member list, and their certificate falls under your
+   * governance.
+   *
+   * They cannot sign when this returns: `status` is `awaiting_member` until they
+   * complete identity verification. Redirect them to `data.completionUrl`, or let
+   * the invitation email carry them there.
+   *
+   * Requires `signer:sponsor`, a paid plan, and a funded wallet.
+   *
+   * @param {object}  opts
+   * @param {string}  opts.email
+   * @param {string} [opts.name]              shown on the invitation; the certificate
+   *                                          carries the name on their verified ID
+   * @param {'ses'|'ades'|'qes'} [opts.tier='ades']
+   * @param {boolean} [opts.restrictToSponsor=true]  only signs your documents
+   *
+   * @example
+   * const { data } = await client.signers.sponsor({ email: 'jane@example.com', tier: 'ades' });
+   * return redirect(data.completionUrl);
+   */
+  sponsor({ email, name, tier = 'ades', restrictToSponsor = true } = {}) {
+    if (!email) throw new Error('signers.sponsor: email is required');
+    return this._http.post('/sdk/v1/signers/sponsor', {
+      data: { email, ...(name && { name }), tier, restrictToSponsor },
+    });
+  }
+
+  /**
+   * Re-send the account-setup link to a signer you sponsored.
+   *
+   * The original link is returned once and stored hashed, so it cannot be looked up.
+   * This mints a FRESH one, which means any previous link stops working.
+   *
+   * Only works while the account is unclaimed: once the signer has chosen a
+   * password this returns 409 ALREADY_SET_UP, because handing a live account a new
+   * setup link would be a way to take it over. Rate limited to one send every five
+   * minutes per signer.
+   *
+   * Requires `signer:sponsor`.
+   *
+   * @example
+   * try {
+   *   await client.signers.resendSetup('jane@example.com');
+   * } catch (e) {
+   *   if (e.code === 'ALREADY_SET_UP')  // she can sign in, or use forgot-password
+   *   if (e.code === 'RESEND_TOO_SOON') // e.details.data.retryAfterSeconds
+   * }
+   */
+  resendSetup(email) {
+    if (!email) throw new Error('signers.resendSetup: email is required');
+    return this._http.post(
+      `/sdk/v1/signers/${encodeURIComponent(email)}/resend-setup`,
+      { data: {} },
+    );
+  }
+}
+
+module.exports = { SignerResource };

package/src/lib/SigningResource.js

@@ -109,7 +109,7 @@ class SigningResource {
 
     const form = new FormData();
     for (const doc of documents) {
-      _appendDocument(form, doc.data, doc.filename || 'document.pdf');
+      _appendDocument(form, doc.data, doc.filename || 'document.pdf', 'documents');
     }
     form.append('signerName',  signerName);
     if (signerEmail) form.append('signerEmail', signerEmail);
@@ -157,12 +157,16 @@ class SigningResource {
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-function _appendDocument(form, document, filename) {
-  if (Buffer.isBuffer(document)) {
-    form.append('document', document, { filename, contentType: 'application/pdf' });
-  } else if (document && typeof document.pipe === 'function') {
-    // ReadStream
-    form.append('document', document, { filename, contentType: 'application/pdf' });
+/**
+ * @param {string} [field] multipart field name. The single-document endpoint reads
+ *   `document` (multer `.single('document')`); the batch endpoint reads `documents`
+ *   (multer `.array('documents')`). This was hard-coded to 'document' for both, so
+ *   every batchSign call had its files rejected with LIMIT_UNEXPECTED_FILE before
+ *   reaching the handler — the method could never have worked.
+ */
+function _appendDocument(form, document, filename, field = 'document') {
+  if (Buffer.isBuffer(document) || (document && typeof document.pipe === 'function')) {
+    form.append(field, document, { filename, contentType: 'application/pdf' });
   } else {
     throw new Error(`Document must be a Buffer or ReadStream, got ${typeof document}`);
   }