feat(ims-client): support optional ttl for promise token

getPromiseToken accepts an optional third ttl argument. It is included in
the IMS promise token request only when it is a finite number greater
than zero; otherwise the key is omitted. Backward compatible.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: Ravi Verma

packages/spacecat-shared-ims-client/README.md

@@ -58,6 +58,18 @@ async function fetchServiceAccessToken() {
 fetchServiceAccessToken();
 ```
 
+### Creating a Promise Token
+
+An emitter `ImsPromiseClient` creates a promise token from an access token. Pass `true`
+as the second argument to encrypt the returned token. An optional third argument, `ttl`,
+is sent to IMS only when it is a finite number greater than zero; otherwise it is omitted
+and the IMS default applies.
+
+```javascript
+const emitter = ImsPromiseClient.createFrom(context, ImsPromiseClient.CLIENT_TYPE.EMITTER);
+const { promise_token, expires_in } = await emitter.getPromiseToken(accessToken, false, 3600);
+```
+
 ### Getting IMS Organization Details
 
 Retrieve details about an IMS organization by its ID using the `getImsOrganizationDetails` method.

packages/spacecat-shared-ims-client/src/clients/ImsPromiseClient.d.ts

@@ -42,14 +42,20 @@ export class ImsPromiseClient {
    * @param {string} accessToken The access token to get a promise token for.
    * @param {boolean} enableEncryption Whether to enable encryption of the promise
    *                                   token, default false.
+   * @param {number} [ttl] Optional token lifetime sent to IMS. Only included in the
+   *                       request when it is a finite number greater than zero.
    * @throws Error when encryption is enabled and the encryption secret and salt is not set.
    * @returns {Promise<{
    *        promise_token: string,
    *        token_type: string,
    *        expires_in: number,
    *    }>} The promise token.
    */
-  getPromiseToken(accessToken: string, enableEncryption?: boolean): Promise<object>;
+  getPromiseToken(
+    accessToken: string,
+    enableEncryption?: boolean,
+    ttl?: number,
+  ): Promise<object>;
 
   /**
    * Exchanges a promise token for an access token.

packages/spacecat-shared-ims-client/src/clients/ims-promise-client.js

@@ -97,7 +97,15 @@ export default class ImsPromiseClient extends ImsBaseClient {
     this.type = type;
   }
 
-  async getPromiseToken(accessToken, enableEncryption = false) {
+  /**
+   * Creates a promise token for the given access token.
+   * @param {string} accessToken - The authenticating access token.
+   * @param {boolean} [enableEncryption=false] - Whether to encrypt the returned promise token.
+   * @param {number} [ttl] - Optional token lifetime sent to IMS. Only included in the
+   *   request when it is a finite number greater than zero.
+   * @returns {Promise<{promise_token: string, token_type: string, expires_in: number}>}
+   */
+  async getPromiseToken(accessToken, enableEncryption = false, ttl = undefined) {
     if (this.type === ImsPromiseClient.CLIENT_TYPE.CONSUMER) {
       throw new Error('Consumer type does not support getPromiseToken method.');
     }
@@ -112,6 +120,7 @@ export default class ImsPromiseClient extends ImsBaseClient {
           grant_type: 'promise',
           promise_definition_id: this.config.promiseDefinitionId,
           authenticating_token: accessToken,
+          ...(Number.isFinite(ttl) && ttl > 0 ? { ttl } : {}),
         },
         { noAuth: true, noContentType: true },
       );

packages/spacecat-shared-ims-client/test/clients/ims-promise-client.test.js

@@ -270,6 +270,58 @@ describe('ImsPromiseClient', () => {
     });
   });
 
+  describe('getPromiseToken ttl', () => {
+    const testAccessToken = '******';
+    let emitterClient;
+    let capturedBody;
+
+    beforeEach(() => {
+      capturedBody = undefined;
+      emitterClient = ImsPromiseClient.createFrom(
+        mockContext,
+        ImsPromiseClient.CLIENT_TYPE.EMITTER,
+      );
+      nock(`https://${DUMMY_HOST}`)
+        .post(IMS_TOKEN_ENDPOINT, (body) => {
+          capturedBody = body;
+          return true;
+        })
+        .reply(200, {
+          promise_token: 'promiseTokenExample',
+          token_type: 'promise_token',
+          expires_in: 3600,
+        });
+    });
+
+    it('sends ttl when it is a positive number', async () => {
+      const result = await emitterClient.getPromiseToken(testAccessToken, false, 3600);
+      expect(capturedBody).to.include('name="ttl"\r\n\r\n3600\r\n');
+      expect(capturedBody).to.include('name="grant_type"\r\n\r\npromise');
+      expect(result.expires_in).to.equal(3600);
+    });
+
+    it('does not send ttl when omitted', async () => {
+      await emitterClient.getPromiseToken(testAccessToken);
+      expect(capturedBody).to.include('name="grant_type"\r\n\r\npromise');
+      expect(capturedBody).to.not.include('name="ttl"');
+    });
+
+    [
+      ['zero', 0],
+      ['negative', -60],
+      ['NaN', NaN],
+      ['Infinity', Infinity],
+      ['a numeric string', '3600'],
+      ['null', null],
+    ].forEach(([label, ttl]) => {
+      it(`does not send ttl when it is ${label}`, async () => {
+        await emitterClient.getPromiseToken(testAccessToken, false, ttl);
+        expect(capturedBody).to.include('name="grant_type"\r\n\r\npromise');
+        expect(capturedBody).to.not.include('name="ttl"');
+      });
+    });
+  });
+
   describe('exchangeToken', () => {
     const testToken = 'eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjEyMzQ1IiwidHlwZSI6ImFjY2Vzc190b2tlbiIsImNsaWVudF9pZCI6ImV4YW1wbGVfYXBwIiwidXNlcl9pZCI6Ijk4NzY1NDc4OTBBQkNERUYxMjM0NTY3OEBhYmNkZWYxMjM0NTY3ODkuZSIsImFzIjoiaW1zLW5hMSIsImFhX2lkIjoiMTIzNDU2Nzg5MEFCQ0RFRjEyMzQ1Njc4QGFkb2JlLmNvbSIsImNyZWF0ZWRfYXQiOiIxNzEwMjQ3MDAwMDAwIn0.MRDpxgxSHDj4DmA182hPnjMAnKkly-VUJ_bXpQ-J8EQ';
     let consumerClient;