@unboundcx/sdk 4.4.0 → 4.6.0

package/services/documents.js

@@ -0,0 +1,263 @@
+export class DocumentTemplatesService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Create a document template head (draft, no version row).
+   * @param {Object} params
+   * @param {string} params.name - Template name (required)
+   * @param {string} [params.description]
+   * @param {string} [params.tag]
+   * @param {'generative'|'overlay'} [params.engine='generative']
+   * @param {string} [params.sourcePdfStorageId] - Required when engine is overlay
+   * @param {Object} [params.draftSchemaJson]
+   * @param {Object} [params.draftLayoutJson]
+   * @param {Object} [params.draftPageJson]
+   * @param {Object} [params.draftThemeJson]
+   * @returns {Promise<Object>} Created template (includes draft*)
+   */
+  async create({
+    name,
+    description,
+    tag,
+    engine,
+    sourcePdfStorageId,
+    draftSchemaJson,
+    draftLayoutJson,
+    draftPageJson,
+    draftThemeJson,
+  }) {
+    this.sdk.validateParams(
+      { name },
+      {
+        name: { type: 'string', required: true },
+        description: { type: 'string', required: false },
+        tag: { type: 'string', required: false },
+        engine: { type: 'string', required: false },
+        sourcePdfStorageId: { type: 'string', required: false },
+        draftSchemaJson: { type: 'object', required: false },
+        draftLayoutJson: { type: 'object', required: false },
+        draftPageJson: { type: 'object', required: false },
+        draftThemeJson: { type: 'object', required: false },
+      },
+    );
+
+    const body = { name };
+    if (description !== undefined) body.description = description;
+    if (tag !== undefined) body.tag = tag;
+    if (engine !== undefined) body.engine = engine;
+    if (sourcePdfStorageId !== undefined) {
+      body.sourcePdfStorageId = sourcePdfStorageId;
+    }
+    if (draftSchemaJson !== undefined) body.draftSchemaJson = draftSchemaJson;
+    if (draftLayoutJson !== undefined) body.draftLayoutJson = draftLayoutJson;
+    if (draftPageJson !== undefined) body.draftPageJson = draftPageJson;
+    if (draftThemeJson !== undefined) body.draftThemeJson = draftThemeJson;
+
+    return this.sdk._fetch('/documents/templates', 'POST', { body });
+  }
+
+  /**
+   * List document templates (not deleted). Returns draft* for authoring.
+   * @param {Object} [params]
+   * @param {string} [params.tag]
+   * @param {string} [params.status]
+   * @param {number} [params.limit]
+   * @returns {Promise<{results: Object[]}>}
+   */
+  async list({ tag, status, limit } = {}) {
+    const query = {};
+    if (tag) query.tag = tag;
+    if (status) query.status = status;
+    if (limit) query.limit = limit;
+    return this.sdk._fetch('/documents/templates', 'GET', { query });
+  }
+
+  /**
+   * Get a document template by id (head + draft* + published version if any).
+   * @param {string} id
+   * @returns {Promise<Object>}
+   */
+  async get(id) {
+    this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
+    return this.sdk._fetch(`/documents/templates/${id}`, 'GET');
+  }
+
+  /**
+   * Update name/description/tag/draft*. Cannot change engine.
+   * @param {string} id
+   * @param {Object} params
+   * @param {string} [params.name]
+   * @param {string} [params.description]
+   * @param {string} [params.tag]
+   * @param {Object} [params.draftSchemaJson]
+   * @param {Object} [params.draftLayoutJson]
+   * @param {Object} [params.draftPageJson]
+   * @param {Object} [params.draftThemeJson]
+   * @returns {Promise<Object>}
+   */
+  async update(
+    id,
+    {
+      name,
+      description,
+      tag,
+      draftSchemaJson,
+      draftLayoutJson,
+      draftPageJson,
+      draftThemeJson,
+    } = {},
+  ) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+        name: { type: 'string', required: false },
+        description: { type: 'string', required: false },
+        tag: { type: 'string', required: false },
+        draftSchemaJson: { type: 'object', required: false },
+        draftLayoutJson: { type: 'object', required: false },
+        draftPageJson: { type: 'object', required: false },
+        draftThemeJson: { type: 'object', required: false },
+      },
+    );
+
+    const body = {};
+    if (name !== undefined) body.name = name;
+    if (description !== undefined) body.description = description;
+    if (tag !== undefined) body.tag = tag;
+    if (draftSchemaJson !== undefined) body.draftSchemaJson = draftSchemaJson;
+    if (draftLayoutJson !== undefined) body.draftLayoutJson = draftLayoutJson;
+    if (draftPageJson !== undefined) body.draftPageJson = draftPageJson;
+    if (draftThemeJson !== undefined) body.draftThemeJson = draftThemeJson;
+
+    return this.sdk._fetch(`/documents/templates/${id}`, 'PATCH', { body });
+  }
+
+  /**
+   * Snapshot draft* into a new published version and set currentVersionId.
+   * @param {string} id
+   * @returns {Promise<Object>}
+   */
+  async publish(id) {
+    this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
+    return this.sdk._fetch(`/documents/templates/${id}/publish`, 'POST', {
+      body: {},
+    });
+  }
+
+  /**
+   * Soft-delete a document template.
+   * @param {string} id
+   * @returns {Promise<{id: string, deleted: boolean}>}
+   */
+  async delete(id) {
+    this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
+    return this.sdk._fetch(`/documents/templates/${id}`, 'DELETE');
+  }
+}
+
+export class DocumentsService {
+  constructor(sdk) {
+    this.sdk = sdk;
+    this.templates = new DocumentTemplatesService(sdk);
+  }
+
+  /**
+   * Generate a PDF from the published template version.
+   * @param {Object} params
+   * @param {string} params.templateId
+   * @param {Object} params.data
+   * @param {string} [params.versionId]
+   * @param {Object} [params.options]
+   * @param {string} [params.options.filename]
+   * @param {Object} [params.source]
+   * @param {string} [params.source.type]
+   * @param {string} [params.source.id]
+   * @returns {Promise<Object>}
+   */
+  async generate({ templateId, data, versionId, options, source }) {
+    this.sdk.validateParams(
+      { templateId, data },
+      {
+        templateId: { type: 'string', required: true },
+        data: { type: 'object', required: true },
+        versionId: { type: 'string', required: false },
+        options: { type: 'object', required: false },
+        source: { type: 'object', required: false },
+      },
+    );
+
+    const body = { templateId, data };
+    if (versionId !== undefined) body.versionId = versionId;
+    if (options !== undefined) body.options = options;
+    if (source !== undefined) body.source = source;
+
+    return this.sdk._fetch('/documents/generate', 'POST', { body });
+  }
+
+  /**
+   * Preview a PDF from draft* (or a specific versionId). isPreview=1.
+   * @param {Object} params
+   * @param {string} params.templateId
+   * @param {Object} [params.data]
+   * @param {string} [params.versionId]
+   * @returns {Promise<Object>}
+   */
+  async preview({ templateId, data, versionId }) {
+    this.sdk.validateParams(
+      { templateId },
+      {
+        templateId: { type: 'string', required: true },
+        data: { type: 'object', required: false },
+        versionId: { type: 'string', required: false },
+      },
+    );
+
+    const body = { templateId };
+    if (data !== undefined) body.data = data;
+    if (versionId !== undefined) body.versionId = versionId;
+
+    return this.sdk._fetch('/documents/preview', 'POST', { body });
+  }
+
+  /**
+   * Attach a consumer id (e.g. fax document) after send.
+   * @param {Object} params
+   * @param {string} params.id - generatedDocuments id
+   * @param {string} [params.sourceId]
+   * @param {string} [params.sourceType]
+   * @returns {Promise<Object>}
+   */
+  async updateGenerated({ id, sourceId, sourceType }) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+        sourceId: { type: 'string', required: false },
+        sourceType: { type: 'string', required: false },
+      },
+    );
+
+    const body = {};
+    if (sourceId !== undefined) body.sourceId = sourceId;
+    if (sourceType !== undefined) body.sourceType = sourceType;
+
+    return this.sdk._fetch(`/documents/generated/${id}`, 'PATCH', { body });
+  }
+
+  /**
+   * Page count / size for a stored PDF.
+   * @param {Object} params
+   * @param {string} params.storageId
+   * @returns {Promise<{pageCount: number, pageSize: string|null}>}
+   */
+  async inspect({ storageId }) {
+    this.sdk.validateParams(
+      { storageId },
+      { storageId: { type: 'string', required: true } },
+    );
+    return this.sdk._fetch('/documents/inspect', 'POST', { body: { storageId } });
+  }
+}

package/services/externalOAuth.js

@@ -141,6 +141,7 @@ export class ExternalOAuthService {
     scopes,
     authorizationUrl,
     tokenUrl,
+    fromConnectionId,
   }) {
     this.sdk.validateParams(
       { name, provider },
@@ -152,6 +153,7 @@ export class ExternalOAuthService {
         scopes: { type: 'array', required: false },
         authorizationUrl: { type: 'string', required: false },
         tokenUrl: { type: 'string', required: false },
+        fromConnectionId: { type: 'string', required: false },
       },
     );
 
@@ -161,10 +163,30 @@ export class ExternalOAuthService {
     if (scopes) body.scopes = scopes;
     if (authorizationUrl) body.authorizationUrl = authorizationUrl;
     if (tokenUrl) body.tokenUrl = tokenUrl;
+    if (fromConnectionId) body.fromConnectionId = fromConnectionId;
 
     const result = await this.sdk._fetch('/externalOAuth/authorize', 'POST', {
       body,
     });
     return result;
   }
+
+  /**
+   * Check whether a connection can be used for a purpose (e.g. Google Ads / Meta ads).
+   *
+   * @param {string} id
+   * @param {object} [args]
+   * @param {string} [args.purpose='googleAds']
+   * @returns {Promise<object>}
+   */
+  async verify(id, { purpose = 'googleAds' } = {}) {
+    this.sdk.validateParams(
+      { id },
+      { id: { type: 'string', required: true } },
+    );
+
+    return this.sdk._fetch(`/externalOAuth/${id}/verify`, 'POST', {
+      body: { purpose },
+    });
+  }
 }

package/services/fax.js

@@ -78,6 +78,8 @@ export class FaxService {
    *   Required if pdfStorageId and tiffStorageId are not provided.
    * @param {string} [options.pdfStorageId] - Storage ID of the PDF version. Required if storageId is not provided.
    * @param {string} [options.tiffStorageId] - Storage ID of the TIFF version. Required if storageId is not provided.
+   * @param {string} [options.coverStorageId] - Optional cover PDF (or TIFF). Concatenated in front of the body before TIFF convert.
+   * @param {('letter'|'legal'|'a4')} [options.paperSize] - Paper size hint for TIFF conversion. Server also reads PDF MediaBox.
    * @param {string} [options.faxHeader] - TSI header text (defaults to mailbox faxHeader)
    * @param {string} [options.resolution] - Fax resolution (defaults to mailbox resolution)
    * @param {boolean} [options.ecm] - Enable Error Correction Mode (default: true)
@@ -95,6 +97,8 @@ export class FaxService {
    *   toNumber: '+15551234567',
    *   fromNumber: '+15559876543',
    *   storageId: '017xyz788...',
+   *   paperSize: 'legal',
+   *   coverStorageId: '017cover...',
    * });
    * console.log(result.id);     // '158def456...'
    * console.log(result.status); // 'sending'
@@ -120,13 +124,15 @@ export class FaxService {
     storageId,
     pdfStorageId,
     tiffStorageId,
+    coverStorageId,
+    paperSize,
     faxHeader,
     resolution,
     ecm,
     timeout,
   }) {
     this.sdk.validateParams(
-      { faxMailboxId, toNumber, fromNumber },
+      { faxMailboxId, toNumber, fromNumber, coverStorageId, paperSize },
       {
         faxMailboxId: { type: 'string', required: true },
         toNumber: { type: 'string', required: true },
@@ -134,6 +140,8 @@ export class FaxService {
         storageId: { type: 'string', required: false },
         pdfStorageId: { type: 'string', required: false },
         tiffStorageId: { type: 'string', required: false },
+        coverStorageId: { type: 'string', required: false },
+        paperSize: { type: 'string', required: false },
       },
     );
 
@@ -151,6 +159,8 @@ export class FaxService {
         storageId,
         pdfStorageId,
         tiffStorageId,
+        coverStorageId,
+        paperSize,
         faxHeader,
         resolution,
         ecm,

package/services/liveQuery.js

@@ -117,15 +117,20 @@ class LiveQueryHandle {
     filter,
     fields,
     recordTypeId,
+    uoql,
     onEvent,
     onStateChange,
   }) {
     this.manager = manager;
     this.socket = socket;
-    this.object = object;
+    // Internal bookkeeping/log labels need an object-name-shaped string even
+    // in uoql mode - use the literal 'uoql' there (no single object name
+    // exists yet, that's resolved server-side by analyze()).
+    this.object = uoql !== undefined ? 'uoql' : object;
     this.filter = filter;
     this.fields = fields;
     this.recordTypeId = recordTypeId;
+    this.uoql = uoql;
     this.onEvent = onEvent;
     this.onStateChange = onStateChange;
 
@@ -136,7 +141,10 @@ class LiveQueryHandle {
   }
 
   async _subscribe() {
-    const payload = { objectName: this.object, filter: this.filter, fields: this.fields };
+    const payload =
+      this.uoql !== undefined
+        ? { uoql: this.uoql }
+        : { objectName: this.object, filter: this.filter, fields: this.fields };
     if (this.recordTypeId !== undefined) payload.recordTypeId = this.recordTypeId;
 
     const ack = await new Promise((resolve, reject) => {
@@ -249,6 +257,11 @@ class LiveQueryHandle {
  *   this account; falls back to `sdk.socket` if the sdk instance holds one.
  * - object, filter, fields, recordTypeId: subscribe-time query, same shape
  *   as `sdk.objects.query`.
+ * - uoql: subscribe-time query as a UOQL string instead - mutually exclusive
+ *   with object/filter/fields/recordTypeId (throws synchronously if both, or
+ *   neither, are given). Sent to the server as `{ uoql }`; the server runs
+ *   uoql analyze() to resolve it to a fine or coarse subscription. Also
+ *   re-sent verbatim on reconnect resubscribe.
  * - onEvent(frame): called for every 'enter'|'change'|'leave'|'refresh'|
  *   'resync'|'revoked' frame (resync frames are also synthesized locally on
  *   seq gaps and on reconnect).
@@ -257,7 +270,7 @@ class LiveQueryHandle {
  * Resolves to { subscriptionId, mode, unsubscribe() }.
  */
 export async function liveQuery(sdk, args = {}) {
-  const { socket: providedSocket, object, filter, fields, recordTypeId, onEvent, onStateChange } = args;
+  const { socket: providedSocket, object, filter, fields, recordTypeId, uoql, onEvent, onStateChange } = args;
 
   const socket = providedSocket || sdk.socket;
   if (!socket || typeof socket.emit !== 'function' || typeof socket.on !== 'function') {
@@ -267,8 +280,15 @@ export async function liveQuery(sdk, args = {}) {
         'deviation from the locked liveQuery contract, see plan Phase 3',
     );
   }
-  if (!object) {
-    throw new Error('liveQuery :: init :: object is required');
+
+  const hasObjectForm = object !== undefined || filter !== undefined || fields !== undefined || recordTypeId !== undefined;
+  if (uoql !== undefined && hasObjectForm) {
+    throw new Error(
+      'liveQuery :: init :: uoql is mutually exclusive with object/filter/fields/recordTypeId',
+    );
+  }
+  if (uoql === undefined && !object) {
+    throw new Error('liveQuery :: init :: either uoql or object is required');
   }
 
   const manager = getSocketManager(socket);
@@ -279,6 +299,7 @@ export async function liveQuery(sdk, args = {}) {
     filter,
     fields,
     recordTypeId,
+    uoql,
     onEvent,
     onStateChange,
   });