notifications-node-client 8.2.1 → 8.3.0

package/.dockerignore

@@ -0,0 +1 @@
+**/.git/*

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 8.3.0 - 2026-02-19
+
+* Adds Typescript hints (run `npm build:types` to generate type files in `types/`)
+* Bump axios from 1.7.2 to 1.13.5
+
 ## 8.2.1 - 2024-07-03
 
 * Fix a bug where an internal API client function isn't being exposed in the library.

package/Dockerfile

@@ -6,9 +6,12 @@ RUN \
 	echo "Install base packages" \
 	&& apt-get update \
 	&& apt-get install -y --no-install-recommends \
+		awscli \
 		make \
 		gnupg \
+		jq \
 	&& echo "Clean up" \
 	&& rm -rf /var/lib/apt/lists/* /tmp/*
 
 WORKDIR /var/project
+COPY . .

package/Makefile

@@ -14,6 +14,7 @@ build: bootstrap ## Build project (dummy task for CI)
 
 .PHONY: test
 test: ## Run tests
+	npm run check:types
 	npm test
 
 .PHONY: integration-test

package/client/api_client.js

@@ -4,13 +4,12 @@ var defaultRestClient = require('axios').default,
     version = require('../package.json').version;
 
 /**
- * @param urlBase
- * @param serviceId
- * @param apiKeyId
- *
+ * @param {string} apiKeyOrUrl - API key (1 arg), or base URL (2-3 args)
+ * @param {string} [serviceIdOrApiKey] - API key (2 args), or service ID (3 args)
+ * @param {string} [apiKeyId] - API key (3 args)
  * @constructor
  */
-function ApiClient() {
+function ApiClient(apiKeyOrUrl, serviceIdOrApiKey, apiKeyId) {
 
   this.proxy = null;
   this.restClient = defaultRestClient;
@@ -56,67 +55,61 @@ function createToken(requestMethod, requestPath, apiKeyId, serviceId) {
   return createGovukNotifyToken(requestMethod, requestPath, apiKeyId, serviceId);
 }
 
-Object.assign(ApiClient.prototype, {
-
-  /**
-   *
-   * @param {string} path
-   *
-   * @returns {Promise}
-   */
-  get: function(path, additionalOptions) {
-    var options = {
-      method: 'get',
-      url: this.urlBase + path,
-      headers: {
-        'Authorization': 'Bearer ' + createToken('GET', path, this.apiKeyId, this.serviceId),
-        'User-Agent': 'NOTIFY-API-NODE-CLIENT/' + version
-      }
-    };
-    Object.assign(options, additionalOptions)
-    if(this.proxy !== null) options.proxy = this.proxy;
-
-    return this.restClient(options);
-  },
-
-  /**
-   *
-   * @param {string} path
-   * @param {object} data
-   *
-   * @returns {Promise}
-   */
-  post: function(path, data){
-    var options = {
-      method: 'post',
-      url: this.urlBase + path,
-      data: data,
-      headers: {
-        'Authorization': 'Bearer ' + createToken('GET', path, this.apiKeyId, this.serviceId),
-        'User-Agent': 'NOTIFY-API-NODE-CLIENT/' + version
-      }
-    };
-
-    if(this.proxy !== null) options.proxy = this.proxy;
-
-    return this.restClient(options);
-  },
-
-  /**
-   *
-   * @param {object} an axios proxy config
-   */
-  setProxy: function(proxyConfig){
-    this.proxy = proxyConfig
-  },
-
-  /**
-   *
-   * @param {object} an axios instance
-   */
-  setClient: function(restClient){
-    this.restClient = restClient;
-  }
-});
+/**
+ * @param {string} path
+ * @param {import('axios').AxiosRequestConfig} [additionalOptions]
+ * @returns {Promise<import('axios').AxiosResponse>}
+ */
+ApiClient.prototype.get = function(path, additionalOptions) {
+  var options = {
+    method: 'get',
+    url: this.urlBase + path,
+    headers: {
+      'Authorization': 'Bearer ' + createToken('GET', path, this.apiKeyId, this.serviceId),
+      'User-Agent': 'NOTIFY-API-NODE-CLIENT/' + version
+    }
+  };
+  Object.assign(options, additionalOptions)
+  if(this.proxy !== null) options.proxy = this.proxy;
+
+  return this.restClient(options);
+};
+
+/**
+ * @param {string} path
+ * @param {object} data
+ * @returns {Promise<import('axios').AxiosResponse>}
+ */
+ApiClient.prototype.post = function(path, data){
+  var options = {
+    method: 'post',
+    url: this.urlBase + path,
+    data: data,
+    headers: {
+      'Authorization': 'Bearer ' + createToken('GET', path, this.apiKeyId, this.serviceId),
+      'User-Agent': 'NOTIFY-API-NODE-CLIENT/' + version
+    }
+  };
+
+  if(this.proxy !== null) options.proxy = this.proxy;
+
+  return this.restClient(options);
+};
+
+/**
+ * @param {import('axios').AxiosProxyConfig} proxyConfig
+ * @returns {void}
+ */
+ApiClient.prototype.setProxy = function(proxyConfig){
+  this.proxy = proxyConfig
+};
+
+/**
+ * @param {import('axios').AxiosInstance} restClient
+ * @returns {void}
+ */
+ApiClient.prototype.setClient = function(restClient){
+  this.restClient = restClient;
+};
 
 module.exports = ApiClient;

package/client/notification.js

@@ -1,14 +1,72 @@
 var ApiClient = require('./api_client');
 
 /**
- *
- * @param baseUrl
- * @param serviceId
- * @param apiKeyId
- *
+ * @typedef {"sms" | "letter" | "email"} NotificationType
+ */
+
+/**
+ * @typedef {"first" | "second" | "economy" | "europe" | "rest-of-world"} PostageType
+ */
+
+/**
+ * @typedef {Object} TemplateRef
+ * @property {string} id
+ * @property {number} version
+ * @property {string} uri
+ */
+
+/**
+ * @typedef {Object} NotificationResponse
+ * @property {string} id
+ * @property {string} [reference]
+ * @property {NotificationType} type
+ * @property {string} status
+ * @property {{id: string, name: string, version: number}} template
+ * @property {string} body
+ * @property {string} created_at
+ * @property {string} [created_by_name]
+ * @property {string} [sent_at]
+ * @property {string} [completed_at]
+ * @property {string} [scheduled_for]
+ * @property {string} [one_click_unsubscribe]
+ * @property {boolean} is_cost_data_ready
+ * @property {number} [cost_in_pounds]
+ * @property {{billable_sheets_of_paper?: number, postage?: string} | {billable_sms_fragments?: number, international_rate_multiplier?: number, sms_rate?: number}} [cost_details]
+ * @property {string} [email_address]
+ * @property {string} [phone_number]
+ * @property {string} [subject]
+ * @property {string} [line_1]
+ * @property {string} [line_2]
+ * @property {string} [line_3]
+ * @property {string} [line_4]
+ * @property {string} [line_5]
+ * @property {string} [line_6]
+ * @property {string} [line_7]
+ * @property {PostageType} [postage]
+ */
+
+/**
+ * @typedef {Object} TemplateData
+ * @property {string} id
+ * @property {string} name
+ * @property {NotificationType} type
+ * @property {string} created_at
+ * @property {string | null} updated_at
+ * @property {string} created_by
+ * @property {number} version
+ * @property {string} body
+ * @property {string} [subject]
+ * @property {string} [letter_contact_block]
+ * @property {PostageType} [postage]
+ */
+
+/**
+ * @param {string} apiKeyOrUrl - API key (1 arg), or base URL (2-3 args)
+ * @param {string} [serviceIdOrApiKey] - API key (2 args), or service ID (3 args)
+ * @param {string} [apiKeyId] - API key (3 args)
  * @constructor
  */
-function NotifyClient() {
+function NotifyClient(apiKeyOrUrl, serviceIdOrApiKey, apiKeyId) {
   this.apiClient = new (Function.prototype.bind.apply(
       ApiClient,
       [null].concat(Array.prototype.slice.call(arguments))
@@ -126,265 +184,231 @@ function _check_and_encode_file(file, size_limit) {
   return file.toString('base64')
 }
 
-Object.assign(NotifyClient.prototype, {
-  /**
-   * Usage:
-   *
-   * notifyClient = new NotifyClient(urlBase, serviceId, apiKeyId);
-   *
-   * notifyClient.sendEmail(templateId, email, personalisation)
-   *    .then(function (response) {
-   *       //do stuff with response
-   *     })
-   *     .catch(function (error) {
-   *       //deal with errors here
-   *     });
-   *
-   *
-   * @param {String} templateId
-   * @param {String} emailAddress
-   * @param {Object} options
-   *
-   * @returns {Promise}
-   */
-  sendEmail: function (templateId, emailAddress, options) {
-    options = options || {};
-    var err = checkOptionsKeys(['personalisation', 'reference', 'emailReplyToId', 'oneClickUnsubscribeURL'], options)
-    if (err) {
-      return Promise.reject(err);
-    }
-    var personalisation = options.personalisation || undefined,
-      reference = options.reference || undefined,
-      emailReplyToId = options.emailReplyToId || undefined,
-      oneClickUnsubscribeURL = options.oneClickUnsubscribeURL || undefined;
-
-    return this.apiClient.post('/v2/notifications/email',
-      createNotificationPayload('email', templateId, emailAddress, personalisation, reference, emailReplyToId, oneClickUnsubscribeURL));
-  },
-
-  /**
-   *
-   * @param {String} templateId
-   * @param {String} phoneNumber
-   * @param {Object} options
-   *
-   * @returns {Promise}
-   */
-  sendSms: function (templateId, phoneNumber, options) {
-    options = options || {};
-    var err = checkOptionsKeys(['personalisation', 'reference', 'smsSenderId'], options)
-    if (err) {
-      return Promise.reject(err);
-    }
-
-    var personalisation = options.personalisation || undefined;
-    var reference = options.reference || undefined;
-    var smsSenderId = options.smsSenderId || undefined;
-
-    return this.apiClient.post('/v2/notifications/sms',
-      createNotificationPayload('sms', templateId, phoneNumber, personalisation, reference, smsSenderId));
-  },
-
-  /**
-   *
-   * @param {String} templateId
-   * @param {Object} options
-   *
-   * @returns {Promise}
-   */
-  sendLetter: function (templateId, options) {
-    options = options || {};
-    var err = checkOptionsKeys(['personalisation', 'reference'], options)
-    if (err) {
-      return Promise.reject(err);
-    }
-    var personalisation = options.personalisation || undefined;
-    var reference = options.reference || undefined;
-
-    return this.apiClient.post('/v2/notifications/letter',
-      createNotificationPayload('letter', templateId, undefined, personalisation, reference));
-  },
-
-  sendPrecompiledLetter: function(reference, pdf_file, postage) {
-    var postage = postage || undefined
-    var content = _check_and_encode_file(pdf_file, 5)
-    var notification = {
-      "reference": reference,
-      "content": content
-    }
-    if (postage != undefined) {
-      notification["postage"] = postage
-    }
-    return this.apiClient.post('/v2/notifications/letter', notification);
-  },
-
-  /**
-   *
-   * @param {String} notificationId
-   *
-   * @returns {Promise}
-   */
-  getNotificationById: function(notificationId) {
-    return this.apiClient.get('/v2/notifications/' + notificationId);
-  },
-
-  /**
-   *
-   * @param {String} templateType
-   * @param {String} status
-   * @param {String} reference
-   * @param {String} olderThanId
-   *
-   * @returns {Promise}
-   *
-   */
-  getNotifications: function(templateType, status, reference, olderThanId) {
-    return this.apiClient.get('/v2/notifications' + buildGetAllNotificationsQuery(templateType, status, reference, olderThanId));
-  },
-
-  /**
-   *
-   * @param {String} notificationId
-   *
-   * @returns {Promise}
-   */
-  getPdfForLetterNotification: function(notificationId) {
-    const url = '/v2/notifications/' + notificationId + '/pdf'
-
-    // Unlike other requests, we expect a successful response as an arraybuffer and an error as JSON
-    // Axios does not support flexible response types so we will need to handle the error case ourselves below
-    return this.apiClient.get(url, { responseType: 'arraybuffer' })
-    .then(function(response) {
-      var pdf = Buffer.from(response.data, "base64")
-      return pdf
-    })
-    .catch(function(error) {
-      // If we receive an error, as the response is an arraybuffer rather than our usual JSON
-      // we need to convert it to JSON to be read by the user
-      string_of_error_body = new TextDecoder().decode(error.response.data);
-
-      // Then we replace the error data with the JSON error rather than the arraybuffer of the error
-      error.response.data = JSON.parse(string_of_error_body);
-
-      // and rethrow to let the user handle the error
-      throw error
-    });
-  },
-
-  /**
-   *
-   * @param {String} templateId
-   *
-   * @returns {Promise}
-   */
-  getTemplateById: function(templateId) {
-    return this.apiClient.get('/v2/template/' + templateId);
-  },
-
-  /**
-   *
-   * @param {String} templateId
-   * @param {Integer} version
-   *
-   * @returns {Promise}
-   */
-  getTemplateByIdAndVersion: function(templateId, version) {
-    return this.apiClient.get('/v2/template/' + templateId + '/version/' + version);
-  },
-
-  /**
-   *
-   * @param {String} type
-   *
-   * @returns {Promise}
-   */
-  getAllTemplates: function(templateType) {
-    let templateQuery = ''
-
-    if (templateType) {
-      templateQuery = '?type=' + templateType;
-    }
-
-    return this.apiClient.get('/v2/templates' + templateQuery);
-  },
-
-  /**
-   *
-   * @param {String} templateId
-   * @param {Dictionary} personalisation
-   *
-   * @returns {Promise}
-   */
-  previewTemplateById: function(templateId, personalisation) {
-
-    let payload = {}
-
-    if (personalisation) {
-      payload.personalisation = personalisation;
-    }
-
-    return this.apiClient.post('/v2/template/' + templateId +  '/preview', payload);
-  },
-
-  /**
-  *
-  * @param {String} olderThan
-  *
-  * @returns {Promise}
-  */
-  getReceivedTexts: function(olderThan){
-    let queryString;
-
-    if (olderThan) {
-      queryString = '?older_than=' + olderThan;
-    } else {
-      queryString = '';
-    }
-
-    return this.apiClient.get('/v2/received-text-messages' + queryString);
-  },
-
-  /**
-   *
-   * @param {object} an axios proxy config
-   */
-  setProxy: function(proxyConfig) {
-    this.apiClient.setProxy(proxyConfig);
-  },
-
-  /**
-   *
-   * @param {object} an axios instance
-   */
-  setClient: function(client) {
-    this.apiClient.setClient(client);
-  },
-
-  /**
-  *
-  * @param {Buffer} fileData
-  * @param {object} options
-  *
-  * @returns {Dictionary}
-  */
-  prepareUpload: function(fileData, options) {
-    let data = {
-      file: _check_and_encode_file(fileData, 2),
-      filename: null,
-      confirm_email_before_download: null,
-      retention_period: null,
-    }
-
-    if (options !== undefined) {
-      data.filename = options.filename || null;
-      data.confirm_email_before_download = options.confirmEmailBeforeDownload !== undefined ? options.confirmEmailBeforeDownload : null;
-      data.retention_period = options.retentionPeriod || null;
-    }
-
-    return data;
-  },
-
-});
+/**
+ * @param {string} templateId
+ * @param {string} emailAddress
+ * @param {{personalisation?: Object, reference?: string, emailReplyToId?: string, oneClickUnsubscribeURL?: string}} [options]
+ * @returns {Promise<import('axios').AxiosResponse<{id: string, reference?: string, content: {body: string, subject: string, from_email: string, one_click_unsubscribe_url?: string}, uri: string, template: TemplateRef}>>}
+ */
+NotifyClient.prototype.sendEmail = function (templateId, emailAddress, options) {
+  options = options || {};
+  var err = checkOptionsKeys(['personalisation', 'reference', 'emailReplyToId', 'oneClickUnsubscribeURL'], options)
+  if (err) {
+    return Promise.reject(err);
+  }
+  var personalisation = options.personalisation || undefined,
+    reference = options.reference || undefined,
+    emailReplyToId = options.emailReplyToId || undefined,
+    oneClickUnsubscribeURL = options.oneClickUnsubscribeURL || undefined;
+
+  return this.apiClient.post('/v2/notifications/email',
+    createNotificationPayload('email', templateId, emailAddress, personalisation, reference, emailReplyToId, oneClickUnsubscribeURL));
+};
+
+/**
+ * @param {string} templateId
+ * @param {string} phoneNumber
+ * @param {{personalisation?: Object, reference?: string, smsSenderId?: string}} [options]
+ * @returns {Promise<import('axios').AxiosResponse<{id: string, reference?: string, content: {body: string, from_number: string}, uri: string, template: TemplateRef}>>}
+ */
+NotifyClient.prototype.sendSms = function (templateId, phoneNumber, options) {
+  options = options || {};
+  var err = checkOptionsKeys(['personalisation', 'reference', 'smsSenderId'], options)
+  if (err) {
+    return Promise.reject(err);
+  }
+
+  var personalisation = options.personalisation || undefined;
+  var reference = options.reference || undefined;
+  var smsSenderId = options.smsSenderId || undefined;
+
+  return this.apiClient.post('/v2/notifications/sms',
+    createNotificationPayload('sms', templateId, phoneNumber, personalisation, reference, smsSenderId));
+};
+
+/**
+ * @param {string} templateId
+ * @param {{personalisation?: Object, reference?: string}} [options]
+ * @returns {Promise<import('axios').AxiosResponse<{id: string, reference?: string, content: {body: string, subject: string}, uri: string, template: TemplateRef, scheduled_for: string | null}>>}
+ */
+NotifyClient.prototype.sendLetter = function (templateId, options) {
+  options = options || {};
+  var err = checkOptionsKeys(['personalisation', 'reference'], options)
+  if (err) {
+    return Promise.reject(err);
+  }
+  var personalisation = options.personalisation || undefined;
+  var reference = options.reference || undefined;
+
+  return this.apiClient.post('/v2/notifications/letter',
+    createNotificationPayload('letter', templateId, undefined, personalisation, reference));
+};
+
+/**
+ * @param {string} reference
+ * @param {Buffer | string} pdf_file
+ * @param {"first" | "second" | "economy" | "europe" | "rest-of-world"} [postage]
+ * @returns {Promise<import('axios').AxiosResponse<{id: string, reference: string, postage: PostageType}>>}
+ */
+NotifyClient.prototype.sendPrecompiledLetter = function(reference, pdf_file, postage) {
+  var postage = postage || undefined
+  var content = _check_and_encode_file(pdf_file, 5)
+  var notification = {
+    "reference": reference,
+    "content": content
+  }
+  if (postage != undefined) {
+    notification["postage"] = postage
+  }
+  return this.apiClient.post('/v2/notifications/letter', notification);
+};
+
+/**
+ * @param {string} notificationId
+ * @returns {Promise<import('axios').AxiosResponse<NotificationResponse>>}
+ */
+NotifyClient.prototype.getNotificationById = function(notificationId) {
+  return this.apiClient.get('/v2/notifications/' + notificationId);
+};
+
+/**
+ * @param {string} [templateType]
+ * @param {string} [status]
+ * @param {string} [reference]
+ * @param {string} [olderThanId]
+ * @returns {Promise<import('axios').AxiosResponse<{notifications: NotificationResponse[], links: {current: string, next: string}}>>}
+ */
+NotifyClient.prototype.getNotifications = function(templateType, status, reference, olderThanId) {
+  return this.apiClient.get('/v2/notifications' + buildGetAllNotificationsQuery(templateType, status, reference, olderThanId));
+};
+
+/**
+ * @param {string} notificationId
+ * @returns {Promise<Buffer>}
+ */
+NotifyClient.prototype.getPdfForLetterNotification = function(notificationId) {
+  const url = '/v2/notifications/' + notificationId + '/pdf'
+
+  // Unlike other requests, we expect a successful response as an arraybuffer and an error as JSON
+  // Axios does not support flexible response types so we will need to handle the error case ourselves below
+  return this.apiClient.get(url, { responseType: 'arraybuffer' })
+  .then(function(response) {
+    var pdf = Buffer.from(response.data, "base64")
+    return pdf
+  })
+  .catch(function(error) {
+    // If we receive an error, as the response is an arraybuffer rather than our usual JSON
+    // we need to convert it to JSON to be read by the user
+    string_of_error_body = new TextDecoder().decode(error.response.data);
+
+    // Then we replace the error data with the JSON error rather than the arraybuffer of the error
+    error.response.data = JSON.parse(string_of_error_body);
+
+    // and rethrow to let the user handle the error
+    throw error
+  });
+};
+
+/**
+ * @param {string} templateId
+ * @returns {Promise<import('axios').AxiosResponse<TemplateData>>}
+ */
+NotifyClient.prototype.getTemplateById = function(templateId) {
+  return this.apiClient.get('/v2/template/' + templateId);
+};
+
+/**
+ * @param {string} templateId
+ * @param {number} version
+ * @returns {Promise<import('axios').AxiosResponse<TemplateData>>}
+ */
+NotifyClient.prototype.getTemplateByIdAndVersion = function(templateId, version) {
+  return this.apiClient.get('/v2/template/' + templateId + '/version/' + version);
+};
+
+/**
+ * @param {NotificationType} [templateType]
+ * @returns {Promise<import('axios').AxiosResponse<{templates: TemplateData[]}>>}
+ */
+NotifyClient.prototype.getAllTemplates = function(templateType) {
+  let templateQuery = ''
+
+  if (templateType) {
+    templateQuery = '?type=' + templateType;
+  }
+
+  return this.apiClient.get('/v2/templates' + templateQuery);
+};
+
+/**
+ * @param {string} templateId
+ * @param {Object} [personalisation]
+ * @returns {Promise<import('axios').AxiosResponse<{id: string, type: NotificationType, version: number, body: string, html?: string, subject?: string, postage?: PostageType}>>}
+ */
+NotifyClient.prototype.previewTemplateById = function(templateId, personalisation) {
+
+  let payload = {}
+
+  if (personalisation) {
+    payload.personalisation = personalisation;
+  }
+
+  return this.apiClient.post('/v2/template/' + templateId +  '/preview', payload);
+};
+
+/**
+ * @param {string} [olderThan]
+ * @returns {Promise<import('axios').AxiosResponse<{received_text_messages: Array<{id: string, user_number: string, notify_number: string, created_at: string, service_id: string, content: string}>, links: {current: string, next: string}}>>}
+ */
+NotifyClient.prototype.getReceivedTexts = function(olderThan){
+  let queryString;
+
+  if (olderThan) {
+    queryString = '?older_than=' + olderThan;
+  } else {
+    queryString = '';
+  }
+
+  return this.apiClient.get('/v2/received-text-messages' + queryString);
+};
+
+/**
+ * @param {import('axios').AxiosProxyConfig} proxyConfig
+ * @returns {void}
+ */
+NotifyClient.prototype.setProxy = function(proxyConfig) {
+  this.apiClient.setProxy(proxyConfig);
+};
+
+/**
+ * @param {import('axios').AxiosInstance} client
+ * @returns {void}
+ */
+NotifyClient.prototype.setClient = function(client) {
+  this.apiClient.setClient(client);
+};
+
+/**
+ * @param {Buffer | string} fileData
+ * @param {{filename?: string, confirmEmailBeforeDownload?: boolean, retentionPeriod?: string}} [options]
+ * @returns {{file: string, filename: string | null, confirm_email_before_download: boolean | null, retention_period: string | null}}
+ */
+NotifyClient.prototype.prepareUpload = function(fileData, options) {
+  let data = {
+    file: _check_and_encode_file(fileData, 2),
+    filename: null,
+    confirm_email_before_download: null,
+    retention_period: null,
+  }
+
+  if (options !== undefined) {
+    data.filename = options.filename || null;
+    data.confirm_email_before_download = options.confirmEmailBeforeDownload !== undefined ? options.confirmEmailBeforeDownload : null;
+    data.retention_period = options.retentionPeriod || null;
+  }
+
+  return data;
+};
 
 module.exports = {
   NotifyClient: NotifyClient

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notifications-node-client",
-  "version": "8.2.1",
+  "version": "8.3.0",
   "homepage": "https://docs.notifications.service.gov.uk/node.html",
   "repository": {
     "type": "git",
@@ -8,10 +8,13 @@
   },
   "description": "GOV.UK Notify Node.js client ",
   "main": "index.js",
+  "types": "types/index.d.ts",
   "scripts": {
     "test": "mocha \"spec/**/*.js\" && npm run test:markdown:standard",
     "test:markdown:standard": "standard-markdown DOCUMENTATION.md",
-    "integration": "mocha spec/integration/test.js"
+    "integration": "mocha spec/integration/test.js",
+    "build:types": "tsc",
+    "check:types": "tsc --noEmit"
   },
   "engines": {
     "npm": ">=6.14.13",
@@ -24,6 +27,7 @@
     "jsonwebtoken": "^9.0.2"
   },
   "devDependencies": {
+    "@types/node": "^25.3.0",
     "chai": "4.3.4",
     "chai-as-promised": "7.1.1",
     "chai-bytes": "0.1.2",
@@ -34,6 +38,7 @@
     "nock": "9.2.6",
     "optimist": "0.6.1",
     "sinon": "^18.0.0",
-    "standard-markdown": "7.1.0"
+    "standard-markdown": "7.1.0",
+    "typescript": "^5.9.0"
   }
 }

package/spec/integration/test.js

@@ -27,7 +27,7 @@ function make_random_id() {
 
 describer('notification api with a live service', function () {
   // default is 2000 (ms) - api is sometimes slower than this :(
-  this.timeout(40000)
+  this.timeout(120000)
 
   let notifyClient;
   let teamNotifyClient;
@@ -247,7 +247,7 @@ describer('notification api with a live service', function () {
           }
           if (err.response.data && (err.response.data.errors[0].error === "PDFNotReadyError")) {
             count += 1
-            if (count < 7) {
+            if (count < 24) {
               setTimeout(tryClient, 5000)
             } else {
               done(new Error('Too many PDFNotReadyError errors'));

package/spec/types-test.ts

@@ -0,0 +1,153 @@
+// This file is compiled with tsc --noEmit to verify the generated types work correctly.
+// It is NOT run as a test - it only needs to type-check.
+
+import { NotifyClient } from '..';
+
+// Constructor overloads
+const client1 = new NotifyClient('apiKeyId');
+const client2 = new NotifyClient('https://example.com', 'apiKeyId');
+const client3 = new NotifyClient('https://example.com', 'serviceId', 'apiKeyId');
+
+// sendEmail
+async function testSendEmail() {
+  const response = await client1.sendEmail('template-id', 'test@example.com', {
+    personalisation: { name: 'Test' },
+    reference: 'ref-123',
+    emailReplyToId: 'reply-to-id',
+    oneClickUnsubscribeURL: 'https://example.com/unsub',
+  });
+  const id: string = response.data.id;
+  const subject: string = response.data.content.subject;
+  const fromEmail: string = response.data.content.from_email;
+  const unsubUrl: string | undefined = response.data.content.one_click_unsubscribe_url;
+  const templateId: string = response.data.template.id;
+  const templateVersion: number = response.data.template.version;
+  const templateUri: string = response.data.template.uri;
+}
+
+// sendSms
+async function testSendSms() {
+  const response = await client1.sendSms('template-id', '07123456789', {
+    personalisation: { code: '1234' },
+    reference: 'ref-123',
+    smsSenderId: 'sender-id',
+  });
+  const id: string = response.data.id;
+  const body: string = response.data.content.body;
+  const fromNumber: string = response.data.content.from_number;
+}
+
+// sendLetter
+async function testSendLetter() {
+  const response = await client1.sendLetter('template-id', {
+    personalisation: { address_line_1: 'Mr Test', address_line_2: '1 Test St', postcode: 'SW1A 1AA' },
+    reference: 'ref-123',
+  });
+  const id: string = response.data.id;
+  const scheduledFor: string | null = response.data.scheduled_for;
+}
+
+// sendPrecompiledLetter
+async function testSendPrecompiledLetter() {
+  const response = await client1.sendPrecompiledLetter('ref', Buffer.from('pdf'), 'first');
+  const id: string = response.data.id;
+  const postage: string = response.data.postage;
+}
+
+// getNotificationById
+async function testGetNotificationById() {
+  const response = await client1.getNotificationById('notification-id');
+  const id: string = response.data.id;
+  const type: "sms" | "letter" | "email" = response.data.type;
+  const status: string = response.data.status;
+  const body: string = response.data.body;
+  const createdAt: string = response.data.created_at;
+  const isCostDataReady: boolean = response.data.is_cost_data_ready;
+  const emailAddress: string | undefined = response.data.email_address;
+  const phoneNumber: string | undefined = response.data.phone_number;
+  const subject: string | undefined = response.data.subject;
+  const createdByName: string | undefined = response.data.created_by_name;
+  const sentAt: string | undefined = response.data.sent_at;
+  const completedAt: string | undefined = response.data.completed_at;
+  const scheduledFor: string | undefined = response.data.scheduled_for;
+  const oneClickUnsubscribe: string | undefined = response.data.one_click_unsubscribe;
+  const costInPounds: number | undefined = response.data.cost_in_pounds;
+  const line1: string | undefined = response.data.line_1;
+}
+
+// getNotifications
+async function testGetNotifications() {
+  const response = await client1.getNotifications('sms', 'delivered', 'ref', 'older-than-id');
+  const notifications = response.data.notifications;
+  const firstNotification = notifications[0];
+  const type: "sms" | "letter" | "email" = firstNotification.type;
+  const links = response.data.links;
+  const current: string = links.current;
+  const next: string = links.next;
+}
+
+// getPdfForLetterNotification
+async function testGetPdf() {
+  const pdf: Buffer = await client1.getPdfForLetterNotification('notification-id');
+}
+
+// getTemplateById
+async function testGetTemplateById() {
+  const response = await client1.getTemplateById('template-id');
+  const id: string = response.data.id;
+  const name: string = response.data.name;
+  const type: "sms" | "letter" | "email" = response.data.type;
+  const createdAt: string = response.data.created_at;
+  const version: number = response.data.version;
+  const body: string = response.data.body;
+  const letterContactBlock: string | undefined = response.data.letter_contact_block;
+  const postage: string | undefined = response.data.postage;
+}
+
+// getTemplateByIdAndVersion
+async function testGetTemplateByIdAndVersion() {
+  const response = await client1.getTemplateByIdAndVersion('template-id', 3);
+  const id: string = response.data.id;
+}
+
+// getAllTemplates
+async function testGetAllTemplates() {
+  const response = await client1.getAllTemplates('email');
+  const templates = response.data.templates;
+  const first = templates[0];
+  const type: "sms" | "letter" | "email" = first.type;
+}
+
+// previewTemplateById
+async function testPreviewTemplateById() {
+  const response = await client1.previewTemplateById('template-id', { name: 'Test' });
+  const id: string = response.data.id;
+  const type: "sms" | "letter" | "email" = response.data.type;
+  const body: string = response.data.body;
+  const html: string | undefined = response.data.html;
+  const postage: "first" | "second" | "economy" | "europe" | "rest-of-world" | undefined = response.data.postage;
+}
+
+// getReceivedTexts
+async function testGetReceivedTexts() {
+  const response = await client1.getReceivedTexts('older-than-id');
+  const messages = response.data.received_text_messages;
+  const first = messages[0];
+  const userNumber: string = first.user_number;
+  const serviceId: string = first.service_id;
+}
+
+// prepareUpload
+function testPrepareUpload() {
+  const result = client1.prepareUpload(Buffer.from('data'), {
+    filename: 'test.csv',
+    confirmEmailBeforeDownload: true,
+    retentionPeriod: '52 weeks',
+  });
+  const file: string = result.file;
+}
+
+// setProxy
+client1.setProxy({ host: 'proxy.example.com', port: 8080 });
+
+// setClient - accepts axios instance

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationDir": "types",
+    "strict": false,
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "target": "es2015",
+    "module": "commonjs"
+  },
+  "include": ["client/notification.js", "index.js"],
+  "exclude": ["node_modules", "spec"]
+}