@unboundcx/sdk 4.5.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/objects.js

@@ -211,25 +211,27 @@ export class ObjectsService {
    * Update an object record by ID
    *
    * Preferred usage (new signature):
-   * sdk.objects.updateById({ object: 'users', id: 'userId', update: { name: 'Jane' } })
+   * sdk.objects.updateById({ object: 'users', id: 'userId', update: { name: 'Jane' }, skipTriggers: true })
    *
    * Legacy usage (deprecated, but supported):
    * sdk.objects.updateById('users', 'userId', { name: 'Jane' })
    *
    * @param {object} args - Update parameters
+   * @param {boolean} [args.skipTriggers=false] - Skip trigger execution for this write
    * @returns {Promise} Updated object data
    */
   async updateById(...args) {
-    // New signature: updateById({ object, id, update })
+    // New signature: updateById({ object, id, update, skipTriggers })
     if (args.length === 1 && typeof args[0] === 'object' && args[0].object) {
-      const { object, id, update } = args[0];
+      const { object, id, update, skipTriggers = false } = args[0];
 
       this.sdk.validateParams(
-        { object, id, update },
+        { object, id, update, skipTriggers },
         {
           object: { type: 'string', required: true },
           id: { type: 'string', required: true },
           update: { type: 'object', required: true },
+          skipTriggers: { type: 'boolean', required: false },
         },
       );
 
@@ -239,6 +241,7 @@ export class ObjectsService {
           update,
         },
       };
+      if (skipTriggers) params.query = { skipTriggers: true };
 
       return await this.sdk._fetch(`/object/${object}`, 'PUT', params);
     }
@@ -269,13 +272,32 @@ export class ObjectsService {
     throw new Error('Invalid arguments for updateById method');
   }
 
-  async update({ object, where, update }) {
+  /**
+   * Update records matching a where clause.
+   *
+   * @param {object} args
+   * @param {string} args.object
+   * @param {object} args.where
+   * @param {object} args.update
+   * @param {boolean} [args.skipTriggers=false] - Do not run triggers for this write
+   * @returns {Promise} Update result
+   *
+   * @example
+   * await sdk.objects.update({
+   *   object: 'people',
+   *   where: { id: '013…' },
+   *   update: { leadScore: 200 },
+   *   skipTriggers: true,
+   * });
+   */
+  async update({ object, where, update, skipTriggers = false }) {
     this.sdk.validateParams(
-      { object, where, update },
+      { object, where, update, skipTriggers },
       {
         object: { type: 'string', required: true },
         where: { type: 'object', required: true },
         update: { type: 'object', required: true },
+        skipTriggers: { type: 'boolean', required: false },
       },
     );
 
@@ -285,6 +307,7 @@ export class ObjectsService {
         update,
       },
     };
+    if (skipTriggers) params.query = { skipTriggers: true };
 
     const result = await this.sdk._fetch(`/object/${object}`, 'PUT', params);
     return result;
@@ -294,28 +317,31 @@ export class ObjectsService {
    * Create a new object record
    *
    * Preferred usage (new signature):
-   * sdk.objects.create({ object: 'users', body: { name: 'John', email: 'john@example.com' } })
+   * sdk.objects.create({ object: 'users', body: { name: 'John', email: 'john@example.com' }, skipTriggers: true })
    *
    * Legacy usage (deprecated, but supported):
    * sdk.objects.create('users', { name: 'John', email: 'john@example.com' })
    *
    * @param {object} args - Creation parameters
+   * @param {boolean} [args.skipTriggers=false] - Skip trigger execution for this write
    * @returns {Promise} Created object data
    */
   async create(...args) {
-    // New signature: create({ object, body })
+    // New signature: create({ object, body, skipTriggers })
     if (args.length === 1 && typeof args[0] === 'object' && args[0].object) {
-      const { object, body } = args[0];
+      const { object, body, skipTriggers = false } = args[0];
 
       this.sdk.validateParams(
-        { object, body },
+        { object, body, skipTriggers },
         {
           object: { type: 'string', required: true },
           body: { type: 'object', required: true },
+          skipTriggers: { type: 'boolean', required: false },
         },
       );
 
       const params = { body };
+      if (skipTriggers) params.query = { skipTriggers: true };
       return await this.sdk._fetch(`/object/${object}`, 'POST', params);
     }
 
@@ -338,12 +364,29 @@ export class ObjectsService {
     throw new Error('Invalid arguments for create method');
   }
 
-  async delete({ object, where }) {
+  /**
+   * Delete records matching a where clause.
+   *
+   * @param {object} args
+   * @param {string} args.object
+   * @param {object} args.where
+   * @param {boolean} [args.skipTriggers=false] - Do not run triggers for this write
+   * @returns {Promise} Delete result
+   *
+   * @example
+   * await sdk.objects.delete({
+   *   object: 'people',
+   *   where: { id: '013…' },
+   *   skipTriggers: true,
+   * });
+   */
+  async delete({ object, where, skipTriggers = false }) {
     this.sdk.validateParams(
-      { object, where },
+      { object, where, skipTriggers },
       {
         object: { type: 'string', required: true },
         where: { type: 'object', required: true },
+        skipTriggers: { type: 'boolean', required: false },
       },
     );
 
@@ -352,17 +395,31 @@ export class ObjectsService {
         where,
       },
     };
+    if (skipTriggers) params.query = { skipTriggers: true };
 
     const result = await this.sdk._fetch(`/object/${object}`, 'DELETE', params);
     return result;
   }
 
-  async deleteById({ object, id }) {
+  /**
+   * Delete a record by id.
+   *
+   * @param {object} args
+   * @param {string} args.object
+   * @param {string} args.id
+   * @param {boolean} [args.skipTriggers=false] - Do not run triggers for this write
+   * @returns {Promise} Delete result
+   *
+   * @example
+   * await sdk.objects.deleteById({ object: 'people', id: '013…', skipTriggers: true });
+   */
+  async deleteById({ object, id, skipTriggers = false }) {
     this.sdk.validateParams(
-      { object, id },
+      { object, id, skipTriggers },
       {
         object: { type: 'string', required: true },
         id: { type: 'string', required: true },
+        skipTriggers: { type: 'boolean', required: false },
       },
     );
 
@@ -373,6 +430,7 @@ export class ObjectsService {
         },
       },
     };
+    if (skipTriggers) params.query = { skipTriggers: true };
 
     const result = await this.sdk._fetch(`/object/${object}`, 'DELETE', params);
     return result;
@@ -942,4 +1000,83 @@ export class ObjectsService {
     );
     return result;
   }
+
+  /**
+   * List Google Ads customer IDs for an OAuth connection.
+   *
+   * @param {object} args
+   * @param {string} args.connectionId
+   * @returns {Promise<{results: object[], warning?: string|null}>}
+   */
+  async listGoogleAdAccounts({ connectionId }) {
+    this.sdk.validateParams(
+      { connectionId },
+      { connectionId: { type: 'string', required: true } },
+    );
+    return this.sdk._fetch('/object/ad-catalog/google/accounts', 'GET', {
+      query: { connectionId },
+    });
+  }
+
+  /**
+   * List Google Ads campaigns for a customer.
+   *
+   * @param {object} args
+   * @param {string} args.connectionId
+   * @param {string} args.customerId
+   * @param {string} [args.loginCustomerId]
+   * @returns {Promise<{results: object[]}>}
+   */
+  async listGoogleAdCampaigns({ connectionId, customerId, loginCustomerId }) {
+    this.sdk.validateParams(
+      { connectionId, customerId },
+      {
+        connectionId: { type: 'string', required: true },
+        customerId: { type: 'string', required: true },
+      },
+    );
+    const query = { connectionId, customerId };
+    if (loginCustomerId) query.loginCustomerId = loginCustomerId;
+    return this.sdk._fetch('/object/ad-catalog/google/campaigns', 'GET', {
+      query,
+    });
+  }
+
+  /**
+   * List Meta ad accounts for an OAuth connection.
+   *
+   * @param {object} args
+   * @param {string} args.connectionId
+   * @returns {Promise<{results: object[]}>}
+   */
+  async listMetaAdAccounts({ connectionId }) {
+    this.sdk.validateParams(
+      { connectionId },
+      { connectionId: { type: 'string', required: true } },
+    );
+    return this.sdk._fetch('/object/ad-catalog/meta/accounts', 'GET', {
+      query: { connectionId },
+    });
+  }
+
+  /**
+   * List Meta campaigns for an ad account.
+   *
+   * @param {object} args
+   * @param {string} args.connectionId
+   * @param {string} args.adAccountId
+   * @returns {Promise<{results: object[]}>}
+   */
+  async listMetaAdCampaigns({ connectionId, adAccountId }) {
+    this.sdk.validateParams(
+      { connectionId, adAccountId },
+      {
+        connectionId: { type: 'string', required: true },
+        adAccountId: { type: 'string', required: true },
+      },
+    );
+    return this.sdk._fetch('/object/ad-catalog/meta/campaigns', 'GET', {
+      query: { connectionId, adAccountId },
+    });
+  }
 }