@certysign/sdk 2.3.0 → 2.5.0

package/src/lib/BillingResource.js

@@ -0,0 +1,90 @@
+/**
+ * client.billing — what the organisation has, and what things cost.
+ *
+ * Read-only by design. Topping up, changing plan and editing auto-top-up are done
+ * from the CertySign dashboard by a person, not by an API key: a key is a bearer
+ * token that can leak, and a leaked key must not be able to spend or to change what
+ * the organisation is billed.
+ *
+ * Requires the `billing:read` scope.
+ */
+class BillingResource {
+  constructor(http) {
+    this._http = http;
+  }
+
+  /**
+   * Token balance and wallet standing.
+   *
+   * `availableBalance` is the number to spend against — `balance` includes tokens
+   * already reserved by operations in flight. A `status` of 'suspended' means
+   * chargeable calls are refused even when the balance looks healthy.
+   *
+   * @example
+   * const { data } = await client.billing.wallet();
+   * console.log(`${data.availableBalance} ${data.currency} available`);
+   */
+  wallet() {
+    return this._http.get('/sdk/v1/billing/wallet');
+  }
+
+  /**
+   * What an operation will cost, and whether you can currently cover it.
+   *
+   * Call this BEFORE a large batch. One answer up front beats discovering
+   * INSUFFICIENT_BALANCE halfway through, with some documents signed and charged
+   * and others not.
+   *
+   * @param {object}  opts
+   * @param {string}  opts.operationType      e.g. 'document_signing', 'certificate_issuance'
+   * @param {string} [opts.operationSubType]  e.g. 'ADVANCED', 'ADES'
+   * @param {number} [opts.quantity=1]        how many — the total is priced for all of them
+   * @param {number} [opts.additionalSigners=0]
+   *
+   * @example
+   * const { data } = await client.billing.quote({
+   *   operationType: 'document_signing',
+   *   operationSubType: 'ADVANCED',
+   *   quantity: documents.length,
+   * });
+   * if (!data.canAfford) throw new Error(`Need ${data.tokensTotal}, have ${data.availableBalance}`);
+   */
+  quote({ operationType, operationSubType, quantity = 1, additionalSigners = 0 } = {}) {
+    if (!operationType) throw new Error('billing.quote: operationType is required');
+    const qs = new URLSearchParams({
+      operationType,
+      ...(operationSubType && { operationSubType }),
+      quantity: String(quantity),
+      additionalSigners: String(additionalSigners),
+    });
+    return this._http.get(`/sdk/v1/billing/quote?${qs.toString()}`);
+  }
+
+  /**
+   * Wallet history — what was charged, for what, and when.
+   *
+   * @param {object} [opts]
+   * @param {number} [opts.limit=50]   capped at 200
+   * @param {number} [opts.skip=0]
+   * @param {string} [opts.type]       filter by transaction type
+   * @param {string} [opts.status]     filter by status
+   */
+  transactions({ limit = 50, skip = 0, type, status } = {}) {
+    const qs = new URLSearchParams({ limit: String(limit), skip: String(skip) });
+    if (type) qs.set('type', type);
+    if (status) qs.set('status', status);
+    return this._http.get(`/sdk/v1/billing/transactions?${qs.toString()}`);
+  }
+
+  /** The subscription plan and the feature flags that come with it. */
+  plan() {
+    return this._http.get('/sdk/v1/billing/plan');
+  }
+
+  /** The full price list, for showing costs without a call per item. */
+  pricing() {
+    return this._http.get('/sdk/v1/billing/pricing');
+  }
+}
+
+module.exports = { BillingResource };

package/src/lib/EnvelopeResource.js

@@ -1,249 +1,306 @@
-/**
- * @fileoverview EnvelopeResource — full envelope lifecycle management
- *
- * Covers the complete envelope CRUD plus document management:
- *  - create()          POST /sdk/v1/envelopes
- *  - get()             GET  /sdk/v1/envelopes/:id
- *  - list()            GET  /sdk/v1/envelopes
- *  - uploadDocuments() POST /sdk/v1/envelopes/:id/documents
- *  - send()            POST /sdk/v1/envelopes/:id/send
- *  - sign()            POST /sdk/v1/envelopes/:id/sign
- *  - getDocument()     GET  /sdk/v1/envelopes/:id/documents/:docId
- *  - getAuditTrail()   GET  /sdk/v1/envelopes/:id/audit
- */
-
-'use strict';
-
-const FormData = require('form-data');
-
-class EnvelopeResource {
-  /** @param {import('../lib/HttpClient').HttpClient} http */
-  constructor(http) {
-    this._http = http;
-  }
-
-  // ── Create ─────────────────────────────────────────────────────────────────
-
-  /**
-   * Create a new signing envelope.
-   *
-   * Envelopes are containers for documents and signature requests.
-   * After creation, upload documents (uploadDocuments), then send
-   * the envelope (send) to make it ready for signing.
-   *
-   * @param {CreateEnvelopeOptions} options
-   * @returns {Promise<EnvelopeResult>}
-   *
-   * @example
-   * const { data } = await client.envelopes.create({
-   *   title:       'NHIF Reimbursement Claim Q1-2026',
-   *   signers: [{
-   *     name:  'Dr. Grace Mwangi',
-   *     email: 'g.mwangi@nhif.or.ke',
-   *     role:  'primary'
-   *   }],
-   *   metadata: { claimPeriod: 'Q1-2026', department: 'Reimbursements' }
-   * });
-   * const envelopeId = data.envelope._id;
-   */
-  create(options = {}) {
-    const { title, signers = [], message, metadata = {} } = options;
-    if (!title) throw new Error('envelopes.create: title is required');
-    return this._http.post('/sdk/v1/envelopes', {
-      data: { title, signers, message, metadata }
-    });
-  }
-
-  // ── Get ────────────────────────────────────────────────────────────────────
-
-  /**
-   * Get a single envelope by ID with full status, signers, and document list.
-   *
-   * @param {string} envelopeId
-   * @returns {Promise<EnvelopeResult>}
-   */
-  get(envelopeId) {
-    if (!envelopeId) throw new Error('envelopes.get: envelopeId is required');
-    return this._http.get(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}`);
-  }
-
-  // ── List ───────────────────────────────────────────────────────────────────
-
-  /**
-   * List envelopes for the authenticated tenant.
-   *
-   * @param {ListEnvelopesOptions} [options]
-   * @returns {Promise<ListEnvelopesResult>}
-   *
-   * @example
-   * const { data } = await client.envelopes.list({ status: 'completed', limit: 20 });
-   * data.envelopes.forEach(env => console.log(env._id, env.status));
-   */
-  list(options = {}) {
-    const { status, page = 1, limit = 20, search } = options;
-    return this._http.get('/sdk/v1/envelopes', {
-      params: { status, page, limit, search }
-    });
-  }
-
-  // ── Upload Documents ───────────────────────────────────────────────────────
-
-  /**
-   * Upload one or more PDF documents to an existing envelope.
-   *
-   * Must be called after create() and before send().
-   *
-   * @param {string}   envelopeId
-   * @param {DocumentUpload[]} documents
-   * @returns {Promise<UploadResult>}
-   *
-   * @example
-   * await client.envelopes.uploadDocuments('env_abc123', [
-   *   { data: fs.readFileSync('./report.pdf'), filename: 'Q1-report.pdf' }
-   * ]);
-   */
-  uploadDocuments(envelopeId, documents) {
-    if (!envelopeId)        throw new Error('envelopes.uploadDocuments: envelopeId is required');
-    if (!documents?.length) throw new Error('envelopes.uploadDocuments: documents array is required');
-
-    const form = new FormData();
-    for (const doc of documents) {
-      const buf = doc.data;
-      const name = doc.filename || 'document.pdf';
-      if (Buffer.isBuffer(buf)) {
-        form.append('documents', buf, { filename: name, contentType: 'application/pdf' });
-      } else if (buf && typeof buf.pipe === 'function') {
-        form.append('documents', buf, { filename: name, contentType: 'application/pdf' });
-      } else {
-        throw new Error(`Document "${name}" must be a Buffer or ReadStream`);
-      }
-    }
-
-    return this._http.post(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/documents`, {
-      formData: form
-    });
-  }
-
-  // ── Send ───────────────────────────────────────────────────────────────────
-
-  /**
-   * Transition an envelope to 'sent' status, making it ready for signing.
-   *
-   * @param {string} envelopeId
-   * @returns {Promise<EnvelopeResult>}
-   */
-  send(envelopeId) {
-    if (!envelopeId) throw new Error('envelopes.send: envelopeId is required');
-    return this._http.post(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/send`);
-  }
-
-  // ── Sign ───────────────────────────────────────────────────────────────────
-
-  /**
-   * Apply a cryptographic signature to all documents in the envelope.
-   *
-   * This is the core signing step. For SDK requests, interactive 2FA is
-   * bypassed — the API key alone authorises the signature.
-   *
-   * The resulting signatures are PAdES-LTV compliant (PDF Advanced Electronic
-   * Signatures with Long-Term Validation).
-   *
-   * @param {string} envelopeId
-   * @param {SignEnvelopeOptions} [options]
-   * @returns {Promise<SignResult>}
-   *
-   * @example
-   * const result = await client.envelopes.sign('env_abc123', {
-   *   reason:   'Claims approval — NHIF Kenya',
-   *   location: 'Nairobi, Kenya'
-   * });
-   * console.log(result.data.signatures[0].certificate.serialNumber);
-   */
-  sign(envelopeId, options = {}) {
-    if (!envelopeId) throw new Error('envelopes.sign: envelopeId is required');
-    const { reason = 'Digital signature', location = 'Nairobi, Kenya' } = options;
-    return this._http.post(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/sign`, {
-      data: { reason, location }
-    });
-  }
-
-  // ── Download Document ──────────────────────────────────────────────────────
-
-  /**
-   * Download a signed document as a Buffer.
-   *
-   * @param {string} envelopeId
-   * @param {string} documentId
-   * @returns {Promise<Buffer>}  Raw PDF bytes
-   *
-   * @example
-   * const pdfBuffer = await client.envelopes.getDocument('env_abc123', 'doc_xyz789');
-   * fs.writeFileSync('./signed-claim.pdf', pdfBuffer);
-   */
-  async getDocument(envelopeId, documentId) {
-    if (!envelopeId)  throw new Error('envelopes.getDocument: envelopeId is required');
-    if (!documentId)  throw new Error('envelopes.getDocument: documentId is required');
-
-    const response = await this._http.get(
-      `/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/documents/${encodeURIComponent(documentId)}`,
-      { responseType: 'arraybuffer' }
-    );
-    return Buffer.isBuffer(response) ? response : Buffer.from(response);
-  }
-
-  // ── Audit Trail ────────────────────────────────────────────────────────────
-
-  /**
-   * Retrieve the cryptographically verifiable audit trail for an envelope.
-   *
-   * The audit chain is a Merkle-linked log of all envelope events:
-   *  - created, document_uploaded, sent, signed, certificate_issued, completed
-   *
-   * Each entry includes a SHA-256 event hash and chain hash linking it to
-   * the previous entry, making the log tamper-evident.
-   *
-   * @param {string} envelopeId
-   * @returns {Promise<AuditTrailResult>}
-   *
-   * @example
-   * const { data } = await client.envelopes.getAuditTrail('env_abc123');
-   * data.auditTrail.forEach(event => {
-   *   console.log(event.timestamp, event.action, event.eventHash);
-   * });
-   * if (data.chainIntegrity.valid) console.log('Audit chain intact');
-   */
-  getAuditTrail(envelopeId) {
-    if (!envelopeId) throw new Error('envelopes.getAuditTrail: envelopeId is required');
-    return this._http.get(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/audit`);
-  }
-}
-
-/**
- * @typedef {Object} CreateEnvelopeOptions
- * @property {string}   title       - Envelope title
- * @property {{ name: string, email?: string, role?: string }[]} [signers]
- * @property {string}   [message]   - Message to signers
- * @property {Object}   [metadata]
- */
-
-/**
- * @typedef {Object} DocumentUpload
- * @property {Buffer|import('fs').ReadStream} data
- * @property {string} [filename]
- */
-
-/**
- * @typedef {Object} SignEnvelopeOptions
- * @property {string} [reason]
- * @property {string} [location]
- */
-
-/**
- * @typedef {Object} ListEnvelopesOptions
- * @property {'draft'|'sent'|'in_progress'|'completed'|'cancelled'} [status]
- * @property {number} [page]
- * @property {number} [limit]
- * @property {string} [search]
- */
-
-module.exports = { EnvelopeResource };
+/**
+ * @fileoverview EnvelopeResource — full envelope lifecycle management
+ *
+ * Covers the complete envelope CRUD plus document management:
+ *  - create()          POST /sdk/v1/envelopes
+ *  - get()             GET  /sdk/v1/envelopes/:id
+ *  - list()            GET  /sdk/v1/envelopes
+ *  - uploadDocuments() POST /sdk/v1/envelopes/:id/documents
+ *  - send()            POST /sdk/v1/envelopes/:id/send
+ *  - sign()            POST /sdk/v1/envelopes/:id/sign
+ *  - getDocument()     GET  /sdk/v1/envelopes/:id/documents/:docId
+ *  - getAuditTrail()   GET  /sdk/v1/envelopes/:id/audit
+ */
+
+'use strict';
+
+const FormData = require('form-data');
+
+class EnvelopeResource {
+  /** @param {import('../lib/HttpClient').HttpClient} http */
+  constructor(http) {
+    this._http = http;
+  }
+
+  // ── Create ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Create a new signing envelope.
+   *
+   * Envelopes are containers for documents and signature requests.
+   * After creation, upload documents (uploadDocuments), then send
+   * the envelope (send) to make it ready for signing.
+   *
+   * @param {CreateEnvelopeOptions} options
+   * @returns {Promise<EnvelopeResult>}
+   *
+   * @example
+   * const { data } = await client.envelopes.create({
+   *   name:        'NHIF Reimbursement Claim Q1-2026',
+   *   recipients: [{
+   *     name:  'Dr. Grace Mwangi',
+   *     email: 'g.mwangi@nhif.or.ke',
+   *     role:  'primary'
+   *   }],
+   *   metadata: { claimPeriod: 'Q1-2026', department: 'Reimbursements' }
+   * });
+   * const envelopeId = data.envelope._id;
+   */
+  create(options = {}) {
+    // The API reads `name` and `recipients`. This used to post `title` and `signers`,
+    // which the server simply ignored — producing an unnamed envelope with nobody on
+    // it, which then failed at send time with NO_SIGNERS and no hint as to why. Both
+    // spellings are accepted so existing callers keep working, and both are mapped to
+    // what the server actually reads.
+    const {
+      title, name = title,
+      signers, recipients = signers || [],
+      message, description = message,
+      metadata = {},
+      signingOrder, signingSequence, requires2FA, requiresBiometric,
+      biometricFallback, expiresAt,
+    } = options;
+
+    if (!name) throw new Error('envelopes.create: name (or title) is required');
+
+    return this._http.post('/sdk/v1/envelopes', {
+      data: {
+        name,
+        ...(description !== undefined && { description }),
+        recipients,
+        metadata,
+        ...(signingOrder !== undefined && { signingOrder }),
+        ...(signingSequence !== undefined && { signingSequence }),
+        ...(requires2FA !== undefined && { requires2FA }),
+        ...(requiresBiometric !== undefined && { requiresBiometric }),
+        ...(biometricFallback !== undefined && { biometricFallback }),
+        ...(expiresAt !== undefined && { expiresAt }),
+      },
+    });
+  }
+
+  // ── Send ───────────────────────────────────────────────────────────────────
+
+  /**
+   * Send a draft envelope to its recipients for signature.
+   *
+   * Requires the `envelope:send` scope. The envelope must be a draft with at least
+   * one document and one recipient — envelopes produced by the signing endpoints are
+   * already complete and cannot be sent.
+   *
+   * @example
+   * await client.envelopes.send(envelopeId);
+   */
+  send(envelopeId) {
+    if (!envelopeId) throw new Error('envelopes.send: envelopeId is required');
+    return this._http.post(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/send`, { data: {} });
+  }
+
+  /**
+   * Verify an envelope's audit hash chain.
+   *
+   * Requires the `audit:verify` scope. Works on any envelope, however it was
+   * produced — an immediate signing call or a collected signing workflow.
+   *
+   * @example
+   * const { data } = await client.envelopes.verifyAuditChain(envelopeId);
+   * if (!data.valid) throw new Error('Audit trail has been altered');
+   */
+  verifyAuditChain(envelopeId) {
+    if (!envelopeId) throw new Error('envelopes.verifyAuditChain: envelopeId is required');
+    return this._http.post(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/audit/verify`, { data: {} });
+  }
+
+  // ── Get ────────────────────────────────────────────────────────────────────
+
+  /**
+   * Get a single envelope by ID with full status, signers, and document list.
+   *
+   * @param {string} envelopeId
+   * @returns {Promise<EnvelopeResult>}
+   */
+  get(envelopeId) {
+    if (!envelopeId) throw new Error('envelopes.get: envelopeId is required');
+    return this._http.get(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}`);
+  }
+
+  // ── List ───────────────────────────────────────────────────────────────────
+
+  /**
+   * List envelopes for the authenticated tenant.
+   *
+   * @param {ListEnvelopesOptions} [options]
+   * @returns {Promise<ListEnvelopesResult>}
+   *
+   * @example
+   * const { data } = await client.envelopes.list({ status: 'completed', limit: 20 });
+   * data.envelopes.forEach(env => console.log(env._id, env.status));
+   */
+  list(options = {}) {
+    const { status, page = 1, limit = 20, search } = options;
+    return this._http.get('/sdk/v1/envelopes', {
+      params: { status, page, limit, search }
+    });
+  }
+
+  // ── Upload Documents ───────────────────────────────────────────────────────
+
+  /**
+   * Upload one or more PDF documents to an existing envelope.
+   *
+   * Must be called after create() and before send().
+   *
+   * @param {string}   envelopeId
+   * @param {DocumentUpload[]} documents
+   * @returns {Promise<UploadResult>}
+   *
+   * @example
+   * await client.envelopes.uploadDocuments('env_abc123', [
+   *   { data: fs.readFileSync('./report.pdf'), filename: 'Q1-report.pdf' }
+   * ]);
+   */
+  uploadDocuments(envelopeId, documents) {
+    if (!envelopeId)        throw new Error('envelopes.uploadDocuments: envelopeId is required');
+    if (!documents?.length) throw new Error('envelopes.uploadDocuments: documents array is required');
+
+    const form = new FormData();
+    for (const doc of documents) {
+      const buf = doc.data;
+      const name = doc.filename || 'document.pdf';
+      if (Buffer.isBuffer(buf)) {
+        form.append('documents', buf, { filename: name, contentType: 'application/pdf' });
+      } else if (buf && typeof buf.pipe === 'function') {
+        form.append('documents', buf, { filename: name, contentType: 'application/pdf' });
+      } else {
+        throw new Error(`Document "${name}" must be a Buffer or ReadStream`);
+      }
+    }
+
+    return this._http.post(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/documents`, {
+      formData: form
+    });
+  }
+
+  // ── Send ───────────────────────────────────────────────────────────────────
+
+  /**
+   * Transition an envelope to 'sent' status, making it ready for signing.
+   *
+   * @param {string} envelopeId
+   * @returns {Promise<EnvelopeResult>}
+   */
+  send(envelopeId) {
+    if (!envelopeId) throw new Error('envelopes.send: envelopeId is required');
+    return this._http.post(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/send`);
+  }
+
+  // ── Sign ───────────────────────────────────────────────────────────────────
+
+  /**
+   * Apply a cryptographic signature to all documents in the envelope.
+   *
+   * This is the core signing step. For SDK requests, interactive 2FA is
+   * bypassed — the API key alone authorises the signature.
+   *
+   * The resulting signatures are PAdES-LTV compliant (PDF Advanced Electronic
+   * Signatures with Long-Term Validation).
+   *
+   * @param {string} envelopeId
+   * @param {SignEnvelopeOptions} [options]
+   * @returns {Promise<SignResult>}
+   *
+   * @example
+   * const result = await client.envelopes.sign('env_abc123', {
+   *   reason:   'Claims approval — NHIF Kenya',
+   *   location: 'Nairobi, Kenya'
+   * });
+   * console.log(result.data.signatures[0].certificate.serialNumber);
+   */
+  sign(envelopeId, options = {}) {
+    if (!envelopeId) throw new Error('envelopes.sign: envelopeId is required');
+    const { reason = 'Digital signature', location = 'Nairobi, Kenya' } = options;
+    return this._http.post(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/sign`, {
+      data: { reason, location }
+    });
+  }
+
+  // ── Download Document ──────────────────────────────────────────────────────
+
+  /**
+   * Download a signed document as a Buffer.
+   *
+   * @param {string} envelopeId
+   * @param {string} documentId
+   * @returns {Promise<Buffer>}  Raw PDF bytes
+   *
+   * @example
+   * const pdfBuffer = await client.envelopes.getDocument('env_abc123', 'doc_xyz789');
+   * fs.writeFileSync('./signed-claim.pdf', pdfBuffer);
+   */
+  async getDocument(envelopeId, documentId) {
+    if (!envelopeId)  throw new Error('envelopes.getDocument: envelopeId is required');
+    if (!documentId)  throw new Error('envelopes.getDocument: documentId is required');
+
+    const response = await this._http.get(
+      `/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/documents/${encodeURIComponent(documentId)}`,
+      { responseType: 'arraybuffer' }
+    );
+    return Buffer.isBuffer(response) ? response : Buffer.from(response);
+  }
+
+  // ── Audit Trail ────────────────────────────────────────────────────────────
+
+  /**
+   * Retrieve the cryptographically verifiable audit trail for an envelope.
+   *
+   * The audit chain is a Merkle-linked log of all envelope events:
+   *  - created, document_uploaded, sent, signed, certificate_issued, completed
+   *
+   * Each entry includes a SHA-256 event hash and chain hash linking it to
+   * the previous entry, making the log tamper-evident.
+   *
+   * @param {string} envelopeId
+   * @returns {Promise<AuditTrailResult>}
+   *
+   * @example
+   * const { data } = await client.envelopes.getAuditTrail('env_abc123');
+   * data.auditTrail.forEach(event => {
+   *   console.log(event.timestamp, event.action, event.eventHash);
+   * });
+   * if (data.chainIntegrity.valid) console.log('Audit chain intact');
+   */
+  getAuditTrail(envelopeId) {
+    if (!envelopeId) throw new Error('envelopes.getAuditTrail: envelopeId is required');
+    return this._http.get(`/sdk/v1/envelopes/${encodeURIComponent(envelopeId)}/audit`);
+  }
+}
+
+/**
+ * @typedef {Object} CreateEnvelopeOptions
+ * @property {string}   title       - Envelope title
+ * @property {{ name: string, email?: string, role?: string }[]} [signers]
+ * @property {string}   [message]   - Message to signers
+ * @property {Object}   [metadata]
+ */
+
+/**
+ * @typedef {Object} DocumentUpload
+ * @property {Buffer|import('fs').ReadStream} data
+ * @property {string} [filename]
+ */
+
+/**
+ * @typedef {Object} SignEnvelopeOptions
+ * @property {string} [reason]
+ * @property {string} [location]
+ */
+
+/**
+ * @typedef {Object} ListEnvelopesOptions
+ * @property {'draft'|'sent'|'in_progress'|'completed'|'cancelled'} [status]
+ * @property {number} [page]
+ * @property {number} [limit]
+ * @property {string} [search]
+ */
+
+module.exports = { EnvelopeResource };